epics 2.11.0 → 3.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a9354e4e83108afe41607057bd8ce1fcba27fc03476a521269911f1f1fea57f
-  data.tar.gz: 82333eed938cdb0a31fcb54b206a6c5653eef950ee7b120f9487de012e4b22f0
+  metadata.gz: bfb2519dc2e22c76ab739665eae1376bc45f525b8025c158e25606892839bed9
+  data.tar.gz: 29a8b4673f7b494c1a8b07e27865bfee5abe5056e176e29612bc4e08058fb340
 SHA512:
-  metadata.gz: 9d74d5100f8698e179df3d9b7eb3f3b3154d64313b975e6645b99ebdfd389e6b1695021640f39b753c685d47055216bf2ecda404c01b1c32f049f16b4caae769
-  data.tar.gz: 3d79c5800b76e7dfbe259e27e8ae1d1f14a77dc99a5b676603bd184a3cff5d3780682f13b14c796a0f92182805cec119ddf4dd585977b4b81f2c0195df00cd2d
+  metadata.gz: 8fbe472fa138faa685cc8c35891d697d114b3cee9086c47ea3bea7a1c36d817176239647e04fc42dca327fcb07bcb0b0ce410d33e3060ccb446e4d4a092f4b50
+  data.tar.gz: bc95a07d0c74576667827a341c3aed4ad1cf2777b000426e351baab9d542c8b0cb0679076ba0660350e96d50c26b7d1ab603217a0ed9d64f4a300f6b96e419e4

data/.gitignore

@@ -17,4 +17,5 @@ mkmf.log
 sbk.key
 /mt940
 *.key
-.idea/
+.idea/
+vendor

data/.semaphore/semaphore.yml

@@ -3,7 +3,7 @@ name: Test
 agent:
   machine:
     type: e1-standard-2
-    os_image: ubuntu2004
+    os_image: ubuntu2204
 blocks:
   - name: Setup
     task:
@@ -16,30 +16,39 @@ blocks:
   - name: Spec versions
     task:
       jobs:
-        - name: "3.1"
+        - name: "3.2"
           commands:
             - checkout
-            - sem-version ruby 3.1
+            - sem-version ruby 3.2
             - cache restore
             - gem install bundler:2.5.19
             - bundle install
             - cache store
             - bundle exec rspec
-        - name: "3.2"
+        - name: "3.3"
           commands:
             - checkout
-            - sem-version ruby 3.2
+            - sem-version ruby 3.3
             - cache restore
             - gem install bundler:2.5.19
             - bundle install
             - cache store
             - bundle exec rspec
-        - name: "3.3"
+        - name: "3.4"
           commands:
             - checkout
-            - sem-version ruby 3.3
+            - sem-version ruby 3.4
             - cache restore
-            - gem install bundler:2.5.19
+            - gem install bundler:2.6.9
+            - bundle install
+            - cache store
+            - bundle exec rspec
+        - name: "4.0"
+          commands:
+            - checkout
+            - sem-version ruby 4.0
+            - cache restore
+            - gem install bundler:4.0.3
             - bundle install
             - cache store
             - bundle exec rspec

data/CHANGELOG.md

@@ -1,5 +1,98 @@
 ### Unreleased
 
+### 3.0.0.rc1
+
+Major release adding EBICS 3.0 (H005) and EBICS 2.4 (H003) support, alongside a
+rewrite of request building into builders/factories/handlers.
+
+**Breaking changes**
+
+- [BREAKING] Default key size for `Epics::Client.setup` raised from 2048 to 4096 bits
+- [BREAKING] Removed internal accessors that were never intended as public API:
+  `Client#a`, `#e`, `#x`, `#bank_x`, `#bank_e`, `#keys=`, `#x_509_certificate`,
+  `#x_509_certificate_hash`, `#x_509_certificates_content`, `#header_request`, and the
+  constants `Epics::Key`, `Epics::Signer`, `Epics::X509Certificate`,
+  `Epics::HeaderRequest`, `Epics::XMLSIG`
+- [BREAKING] `Client#keys` is now recomputed per call; mutating it no longer injects keys
+- [BREAKING] On H005, `Client#HAA` and `Client#order_types` return an array of service
+  hashes (`service_name`, `scope`, `service_option`, `container`, `msg_name`) instead of
+  an array of order-type strings
+
+**Fixes**
+
+- [FIX] Loading a key file with the wrong passphrase raised `OpenSSL::PKey::PKeyError`
+  about one time in 256, when the decrypted garbage happened to be padded correctly.
+  Decryption now verifies it produced a PEM, so a wrong passphrase always raises
+  `OpenSSL::Cipher::CipherError`
+- [FIX] An unreadable certificate in an HPB response raised a bare
+  `OpenSSL::X509::CertificateError`. It now raises `Epics::InvalidCertificateError`
+  naming the HPB response as the source and keeping the OpenSSL message
+- [FIX] `Response#signature_valid?` and `#public_digest_valid?` raised `NoMethodError`
+  when the key they need was not loaded; they now raise `Epics::MissingKeyError` naming
+  it. `#digest_valid?` no longer needs a key at all — it is a plain SHA-256 over the
+  authenticated nodes
+- [BREAKING] Removed `Epics::Builders::MutableBuilder#add_receipt_code`, which emitted
+  `ReceiptCode` inside `mutable` where the schema does not allow it. `ReceiptCode`
+  belongs to `TransferReceipt`, which `TransferReceiptBuilder` already builds
+- [FIX] Removed the `container_flag:` order parameter, which emitted a `ContainerFlag`
+  element that exists in no EBICS schema. The container is expressed by `Container`
+  with a `containerType` attribute, which `container_type:` already emits
+- [ENHANCEMENT] Added the H005-only order types `XEK` (account statements as PDF),
+  `ZSR` (payment status reports) and `YCT` (multi-currency credit transfer). Their BTF
+  mappings existed in the V3 factory but had no order class or client method
+- [BREAKING] `XEK`, `YCT` and `ZSR` raise `Epics::VersionSupportError` on H003/H004
+  instead of `NotImplementedError`, matching every other version mismatch
+- [ENHANCEMENT] `XEK`, `ZSR`, `Z01`, `Z52`, `Z53` and `Z54` accept `scope:`,
+  `service_option:`, `msg_name_version:` and `container_type:`. Defaults are unchanged;
+  Swiss market practice requires a `Scope` and only `ZSR` sent one, so a bank-specific
+  value can now be supplied without patching the gem
+- [ENHANCEMENT] `C54` accepts `scope:`, `msg_name_version:` and `container_type:`, the
+  same options as `C52` and `C53`; `C53` gained `container_type:`. The three camt
+  retrievals now differ only in service name and message type
+- [FIX] `save_keys` discarded any key-file entry it could not map to one of the five
+  keyring slots, so a `host_id` that no longer matched the stored prefix destroyed the
+  bank's public keys on save. Unrecognised entries are now carried through unchanged,
+  and a warning names each one instead of the failure being swallowed
+- [BREAKING] `order_id:` is validated against the EBICS `OrderIDType` range (`A000` to
+  `ZZZZ`). Values below `A000` rendered as e.g. `0002`, which violates the
+  `[A-Z][A-Z0-9]{3}` pattern; they now raise `ArgumentError`. The protocol form
+  (`order_id: 'A000'`) is accepted alongside the integer
+
+- [FIX] `XCT` sent the wrong order type: `CD1` on H003/H004 and the DTAZV service on
+  H005, filing credit transfers as direct debits. It now sends `XCT` on H003/H004.
+  EBICS 3.0 defines no counterpart for XCT, so on H005 it raises
+  `Epics::VersionSupportError` rather than guessing a BTF service
+- [FIX] The electronic signature over order data is again formed with line separators
+  removed, matching 2.x. The refactor had signed the raw document, changing the ES for
+  every upload
+- [BREAKING] Upload order data is now normalized once, on the way in, so the bytes
+  hashed for the electronic signature are the bytes transmitted. Until 3.0 the digest
+  was taken over the normalized document while the raw one was sent, which only
+  verifies against banks that normalize before checking the ES
+- [FIX] H005 `DataDigest` carried an RSA-PSS signature (256 bytes, non-reproducible)
+  instead of the SHA-256 hash of the order data
+- [FIX] `Response#business_error?` treated every `01`-prefixed return code as
+  informational, reporting `011001` (negative acknowledgement) and `011101` (segment
+  number not reached) as success. It now uses an explicit allow-list
+- [BREAKING] Passing only one date-range bound (e.g. `client.STA(from)`) silently
+  omitted the range and fetched the bank's full retention window. Both bounds are
+  mandatory within `DateRange`, so this now raises `ArgumentError`
+- [FIX] `Time` and `DateTime` passed as date-range bounds rendered an `xs:dateTime`
+  with a local offset into an `xs:date` element; they are now coerced to a date
+- [FIX] `C52` requested no container on H005 while `Client#C52` always unzips the
+  response, raising `Zip::Error`. `C52` and `C53` now default to a ZIP container and
+  both accept `container_type:` to override it
+- [BREAKING] Removed `Epics::Services::CryptService#sign`, which had no callers and
+  disagreed with `#encrypt` on how an A005 signature is formed
+- [FIX] `Epics::Client.setup` forwarded its block to `.new`, which yields before the
+  keys are generated, so the block saw an empty keyring and anything touching it —
+  `ini_letter`, `save_keys`, `INI`, `HIA` — failed. It now yields once the client is
+  usable
+- [FIX] `Epics::VersionSupportError` was raised as `raise Error, version, 'below'`,
+  where the third argument is the backtrace, so the direction was dropped and the
+  stack trace destroyed. 2.x-only order types on H005 now report "Support for versions
+  below 3.0" and keep their trace
+
 ### 2.11.0
 
 - [ENHANCEMENT] Added FUL order type (thanks to @scollon-pl)

data/EBICS_REFERENCES.md

@@ -0,0 +1,169 @@
+# EBICS Documentation — Complete Reference
+
+> Last updated: 2026-03-05
+
+---
+
+## 1. Official Specifications (ebics.org)
+
+| Document | Link | Version | Language |
+|---|---|---|---|
+| **Specification main page** | https://www.ebics.org/en/technical-information/ebics-specification | V3.0.2 (current) | EN/DE/FR |
+| **XSD Schemas** | https://www.ebics.org/en/technical-information/ebics-schema | H003/H004/H005 | — |
+| **Implementation Guide** | https://www.ebics.org/en/technical-information/implementation-guide | All | EN/DE |
+| **BTF Mapping (BTD/BTU)** | https://www.ebics.org/en/technical-information/btf-mapping | H005 | EN/DE |
+| **Examples** | https://www.ebics.org/en/technical-information/examples | All | EN |
+| **Additional Standards** | https://www.ebics.org/en/technical-information/additional-standards | All | EN/DE |
+| **Change Requests (archive)** | https://www.ebics.org/en/technical-information/archive-ebics/change-requests | Historical | EN/DE |
+| **Passed CRs** | https://www.ebics.org/en/technical-information/maintain-advance/passed-crs | Maintenance | EN/DE |
+| **Technical News** | https://www.ebics.org/en/current-topics/technical-news | — | EN/DE |
+| **Archived Specifications** | https://www.ebics.org/en/technical-information/archive-ebics/specification | V2.4/2.5 | EN/DE |
+
+---
+
+## 2. Specification PDFs — Direct Download
+
+### Main Specification
+
+| Document | Link | Version |
+|---|---|---|
+| **EBICS V3.0 Spec (SIX)** | https://www.six-group.com/dam/download/banking-services/interbank-clearing/en/standardization/ebics/ebics_3_0.pdf | H005 / V3.0 |
+| **EBICS V3.0 Spec (Gitea mirror)** | https://gitea.szsolutions.ch/Mirror/odoo_account_ebics/raw/branch/15.0/account_ebics/doc/2017-03-29-EBICS_V_3.0-FinalVersion.pdf | H005 / V3.0 |
+| **EBICS V2.5 Spec (CFONB)** | https://www.cfonb.org/fichiers/20130612170023_6_4_EBICS_Specification_2.5_final_2011_05_16_2012_07_01.pdf | H004 / V2.5 |
+| **EBICS V2.4.2 Spec (CFONB)** | https://www.cfonb.org/fichiers/20130612170103_6_7_EBICS_Specification_2.4.2_final_2010_02_16.pdf | H003 / V2.4 |
+
+### Annexes & Supplements
+
+| Document | Link | Content |
+|---|---|---|
+| **Annex 1 — Return Codes** | https://www.cfonb.org/fichiers/20130612170037_6_5_EBICS_Annex1_ReturnCodes_final_16_05_2011_2012_07_01.pdf | All EBICS return codes |
+| **Annex 2 — Order Type Identifiers** | https://www.cfonb.org/fichiers/20140423153546_Annex_2_%E2%80%93_EBICS_Specification_april_2014.pdf | Order type identifiers |
+| **EBICS SC 2021** | https://www.cfonb.org/fichiers/20210420081014_EBICS_SC_2021.pdf | EBICS SC overview |
+
+### France Implementation Guides (CFONB)
+
+| Document | Link | Content |
+|---|---|---|
+| **IG CFONB V2.1.5 (FR)** | https://www.cfonb.org/fichiers/20141029101016_6_10_EBICS_IG_CFONB_VF_2_1_5_2014_06_23.pdf | France implementation guide |
+| **IG CFONB V2.1.4 (EN)** | https://www.cfonb.org/fichiers/20130612170302_6_16_EBICS_IG_CFONB_V2_1.4_english_version_2012_02_24.pdf | France implementation guide (English) |
+| **IG Annex 2 — File names** | https://www.cfonb.org/fichiers/20130612170321_6_17_EBICS_IG_V1.2._Annexe_2_File_names_VE_final_2010_01.pdf | File naming conventions |
+| **IG Annex A3.1 — Certificate error codes** | https://www.cfonb.org/fichiers/20130612170148_6_11_EBICS_IG_V1_1_Annexe_A3_1_Certificates_error_codes_2009_04.pdf | X.509 certificate error codes |
+| **EBICS test scenarios** | https://www.cfonb.org/fichiers/20130612170423_6_21_Proposition_tests_EBICS_V1_0_2009_05_15.pdf | Test scenarios |
+
+### BTF / BTD / BTU (EBICS 3.0)
+
+| Document | Link | Content |
+|---|---|---|
+| **File Format → BTF mapping (CFONB)** | https://www.cfonb.org/sites/www.cfonb.org/files/documents/Tables%20de%20correspondance%20File%20Format%20vers%20BTF-Business%20Transaction%20Format%20(EBICS%20v3.0%20et%20suivantes)%20.pdf | Order type → BTF mapping |
+| **BTF Parameters (konfipay wiki)** | https://wiki.konfipay.de/konfipay/btf-parameters-ebics-3-0 | BTF parameter reference |
+| **CPG — EBICS BTU, BTD and BTF** | https://www.cpg.de/en/ebics-btu-btd-and-btf/ | BTD/BTU/BTF explained |
+| **CPG — EBICS 3.0 innovations** | https://www.cpg.de/en/ebics-3-0/ | EBICS 3.0 overview |
+
+---
+
+## 3. Switzerland — SIX Group
+
+| Document | Link | Content |
+|---|---|---|
+| **Swiss Market Practice Guidelines EBICS 3.0 v1.3** | https://www.six-group.com/dam/download/banking-services/standardization/ebics/market-practice-guidelines-ebics3.0-v1.3-en.pdf | Swiss guidelines H005 |
+| **Swiss Market Practice Guidelines EBICS 3.0 v1.2** | https://www.six-group.com/dam/download/banking-services/standardization/ebics/market-practice-guidelines-ebics3.0-v1.2-en.pdf | Swiss guidelines H005 (older) |
+| **EBICS in Switzerland (overview)** | https://www.six-group.com/dam/download/banking-services/interbank-clearing/en/standardization/ebics/ebics.pdf | EBICS Switzerland overview |
+| **SIX EBICS page** | https://www.six-group.com/en/products-services/banking-services/payment-standardization/standards/ebics.html | SIX EBICS portal |
+
+---
+
+## 4. Germany — Deutsche Kreditwirtschaft / Bundesbank
+
+| Document | Link | Content |
+|---|---|---|
+| **DFÜ-Abkommen — Anlage 3 Datenformate V3.8** | http://www.bayernlb.de/internet/media/de/ir/downloads_1/zahlungsverkehr/richtlinien/2024-11-17_Anlage_3_Datenformate_V3.8.pdf | Data format specification |
+| **ebics.de — Datenformate** | https://www.ebics.de/de/datenformate | Data formats portal |
+| **DFÜ-Verfahren EBICS — DK** | https://die-dk.de/zahlungsverkehr/electronic-banking/dfu-verfahren-ebics/ | DK EBICS page |
+| **Verfahrensregeln EBICS 2025 (Bundesbank)** | https://www.bundesbank.de/resource/blob/964236/6f3129a9aab710eae9b2939e0021a7bc/472B63F073F071307366337C94F8C870/verfahrensregeln-ebics-2025-data.pdf | Procedural rules 2025 |
+| **Verfahrensregeln EBICS V3.9 (Bundesbank)** | https://www.bundesbank.de/resource/blob/764544/2bfc83ca09df0c7a4a53c96caec1ac55/mL/verfahrensregeln-ebics-3-9-data.pdf | Procedural rules V3.9 |
+| **Besondere Bedingungen EBICS 2024 (Bundesbank)** | https://www.bundesbank.de/resource/blob/925930/8b5c5b9da853666a3b1638b0005aa3e4/mL/besondere-bedingungen-ebics-2024-data.pdf | Special conditions |
+| **Deutsche Bank — Order Types (EN)** | https://www.deutsche-bank.de/dam/deutschebank/de/shared/pdf/ebics-dfu-explanation-of-order-type-identifiers-e.pdf | Order type reference (EN) |
+| **Deutsche Bank — Auftragsarten (DE)** | https://www.deutsche-bank.de/dam/deutschebank/de/shared/pdf/ub/ebics-dfue-erlaeuterungen-der-auftragsarten-d.pdf | Order type reference (DE) |
+
+---
+
+## 5. DFÜ-Abkommen — English Translation
+
+| Document | Link | Content |
+|---|---|---|
+| **DFÜ Agreement Appendix 3 (EN, Isabel)** | https://www.isabel.eu/content/dam/knowledge_base_ibs6/documents/en-US/Anlage_3_Datenformate_V29_engl.pdf | Data formats (English translation) |
+
+---
+
+## 6. Reference Implementations (source code)
+
+| Project | Link | Language | Versions |
+|---|---|---|---|
+| **ebics-client-php** | https://github.com/ebics-api/ebics-client-php | PHP | H003/H004/H005 |
+| **ebics-java-client** | https://github.com/ebics-java/ebics-java-client | Java | H004 |
+| **EBICS.php (Synap)** | https://github.com/Synap/EBICS.php | PHP | H003/H004 |
+| **node-ebics-client** | https://github.com/nicemann/node-ebics-client | Node.js | H004 |
+| **epics (railslove)** | https://github.com/railslove/epics | Ruby | H004 |
+| **epics (our fork)** | https://github.com/jplot/epics | Ruby | H003/H004/H005 |
+
+---
+
+## 7. Third-party References
+
+| Resource | Link | Content |
+|---|---|---|
+| **Wikipedia — EBICS** | https://en.wikipedia.org/wiki/Electronic_Banking_Internet_Communication_Standard | Overview |
+| **Wikipedia — DFÜ-Abkommen** | https://de.wikipedia.org/wiki/Abkommen_%C3%BCber_die_Datenfern%C3%BCbertragung_zwischen_Kunden_und_Kreditinstituten | DFÜ-Abkommen (DE) |
+| **Axway — EBICS standard** | https://docs.axway.com/bundle/EBICSClient_11_allOS_en_HTML5/page/the_ebics_standard.html | Axway reference |
+| **Axway — EBICS error codes** | https://docs.axway.com/bundle/TransferCFT_332_LocalAdministrationGuide_allOS_en_HTML5/page/Content/Prots/French/EBICS/r_ebics_error_mess_codes.htm | Error codes (full list) |
+| **IBM — EBICS return codes** | https://www.ibm.com/docs/SS3JSW_5.2.0/com.ibm.help.ebics_client_user_525.doc/EBICS_Client_returncodes_events.html | IBM return codes |
+| **BL Banking — EBICS errors** | https://www.blbanking.de/webhelp/topic/de.businesslogics.banking.web/help/html/appendix/faq-ebicserrors.html | BL Banking error messages |
+| **konfipay — BTF parameters** | https://wiki.konfipay.de/konfipay/btf-parameters-ebics-3-0 | BTF parameters |
+| **Sage XRT — EBICS 3.0 Guide (FR)** | https://sxbe-onlinehelp.sage.com/PDF/SXBE/SXBE.12.1.EBICS.3.0.UserGuide_FR.pdf | Sage user guide |
+| **UBS — EBICS 3.0** | https://www.ubs.com/ch/en/corporates/payment-solutions/cash-management/connection-ubs/ebics.html | UBS EBICS 3.0 page |
+| **BCV — EBICS parameters factsheet** | https://www.bcv.ch/content/dam/bcv/brochure---flyer/44-516e_Fiche-technique-BCV-connect_web.pdf | BCV technical factsheet |
+
+---
+
+## 8. Local XSD Schemas in This Project
+
+XSD schemas are stored in `spec/xsd/`:
+
+```
+spec/xsd/
+├── H003/
+│   └── (H003 schemas)
+├── H004/
+│   ├── ebics_H004.xsd              (H004 root schema)
+│   ├── ebics_hev.xsd               (HEV protocol)
+│   ├── ebics_keymgmt_request_H004.xsd
+│   ├── ebics_keymgmt_response_H004.xsd
+│   ├── ebics_orders_H004.xsd       (89K — order types)
+│   ├── ebics_request_H004.xsd
+│   ├── ebics_response_H004.xsd
+│   ├── ebics_signature.xsd         (S001)
+│   ├── ebics_types_H004.xsd        (86K — types)
+│   └── xmldsig-core-schema.xsd
+└── H005/
+    ├── ebics_H005.xsd              (H005 root schema)
+    ├── ebics_hev.xsd
+    ├── ebics_keymgmt_request_H005.xsd
+    ├── ebics_keymgmt_response_H005.xsd
+    ├── ebics_orders_H005.xsd
+    ├── ebics_request_H005.xsd
+    ├── ebics_response_H005.xsd
+    ├── ebics_signature_S002.xsd    (S002 — A005)
+    ├── ebics_types_H005.xsd
+    └── xmldsig-core-schema.xsd
+```
+
+---
+
+## Notes
+
+- Specifications on **ebics.org** require accepting terms of use before downloading
+- Current version: **V3.0.2** (valid since December 30, 2022)
+- Last BTF list update: **October 23, 2024**
+- **DFÜ-Abkommen Anlage 3** is the reference document for data formats in Germany
+- X/Y/Z prefixed order types = bank-individual (not core EBICS)
+- FUL/FDL = core EBICS H003/H004, removed in H005 (replaced by BTU/BTD)