ksef-client-rails 0.1.0 → 1.0.0

data/lib/ksef/batch/splitter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+
+module Ksef
+  module Batch
+    # Splits the PLAINTEXT package into ≤100 MB parts encrypted with THE SAME session key+IV. A part's
+    # ciphertext is therefore deterministic: {#split} only hashes it and {#encrypt} re-creates it at
+    # upload time, so a single encrypted part is held in memory at a time.
+    class Splitter
+      # Largest plaintext part the contract allows (100 MB, decimal as in the SDKs) — also the default.
+      MAX_PART_SIZE = 100 * 1000 * 1000
+      DEFAULT_PART_SIZE = MAX_PART_SIZE
+
+      # One part: its plaintext byte range plus the size and hash of its ciphertext.
+      Part = Struct.new(:ordinal_number, :offset, :plain_size, :encrypted_size, :encrypted_hash,
+                        keyword_init: true) do
+        # @return [Hash] the `fileParts` entry for the batch session declaration
+        def to_part_info
+          { "ordinalNumber" => ordinal_number, "fileSize" => encrypted_size, "fileHash" => encrypted_hash }
+        end
+      end
+
+      # Split result: metadata of the whole package (`batchFile`) + the list of parts.
+      Result = Struct.new(:batch_file, :parts, keyword_init: true)
+
+      # @param crypto [Ksef::Crypto::CryptographyService]
+      # @param part_size [Integer] maximum plaintext part size, 1..{MAX_PART_SIZE}
+      # @raise [Ksef::ConfigurationError] for a part size outside that range
+      def initialize(crypto:, part_size: DEFAULT_PART_SIZE)
+        unless part_size.is_a?(Integer) && part_size.between?(1, MAX_PART_SIZE)
+          raise ConfigurationError, "part_size must be an Integer in 1..#{MAX_PART_SIZE}, got #{part_size.inspect}"
+        end
+
+        @crypto = crypto
+        @part_size = part_size
+      end
+
+      # @param size [Integer] plaintext package size
+      # @return [Integer] how many parts {#split} makes of a package that size
+      def part_count(size)
+        [(size + @part_size - 1) / @part_size, 1].max
+      end
+
+      # Splits the package and computes the hash and size of every encrypted part.
+      #
+      # @param package_bytes [String] plaintext package bytes (ZIP/tar.gz)
+      # @param encryption [Ksef::Crypto::CryptographyService::EncryptionData] session key+IV
+      # @return [Result]
+      def split(package_bytes, encryption)
+        plain = binary(package_bytes)
+        parts = ranges(plain.bytesize).each_with_index.map do |(offset, plain_size), index|
+          meta = @crypto.metadata(encrypt_range(plain, offset, plain_size, encryption))
+          Part.new(ordinal_number: index + 1, offset: offset, plain_size: plain_size,
+                   encrypted_size: meta.size, encrypted_hash: meta.hash_sha)
+        end
+        Result.new(batch_file: batch_file_info(plain, parts), parts: parts)
+      end
+
+      # The ciphertext of one part — byte for byte what {#split} hashed, given the same key+IV.
+      #
+      # @param package_bytes [String] the package passed to {#split}
+      # @param part [Part]
+      # @param encryption [Ksef::Crypto::CryptographyService::EncryptionData]
+      # @return [String] ciphertext bytes
+      def encrypt(package_bytes, part, encryption)
+        encrypt_range(binary(package_bytes), part.offset, part.plain_size, encryption)
+      end
+
+      private
+
+      # Avoids copying a package that is already binary (a multi-gigabyte one would double in RAM).
+      def binary(bytes)
+        bytes.encoding == Encoding::BINARY ? bytes : bytes.b
+      end
+
+      def ranges(size)
+        return [[0, size]] if size <= @part_size
+
+        (0...size).step(@part_size).map { |offset| [offset, [@part_size, size - offset].min] }
+      end
+
+      def encrypt_range(plain, offset, size, encryption)
+        @crypto.encrypt_aes(plain.byteslice(offset, size), encryption.key, encryption.iv)
+      end
+
+      # `batchFile` = metadata of the PLAINTEXT package + the list of (encrypted) parts.
+      def batch_file_info(plain, parts)
+        meta = @crypto.metadata(plain)
+        {
+          "fileSize" => meta.size,
+          "fileHash" => meta.hash_sha,
+          "fileParts" => parts.map(&:to_part_info)
+        }
+      end
+    end
+  end
+end

data/lib/ksef/batch/uploader.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Batch
+    # Batch session orchestrator: build package → split and encrypt → declare the session → upload
+    # parts sequentially to presigned URLs (`method`+`headers`+`url` from the response; the Java SDK
+    # assumes PUT) → close. The contract limits (50 parts, 5 GB) are checked before anything is encrypted.
+    class Uploader
+      # Most parts a package may have (`batchFile.fileParts`).
+      MAX_PARTS = 50
+      # Largest plaintext package, in bytes (`batchFile.fileSize`).
+      MAX_PACKAGE_SIZE = 5_000_000_000
+      # Package format → `batchFile.compressionType` (the API assumes Zip when it is missing).
+      COMPRESSION_TYPES = { zip: "Zip", tar_gz: "TarGz" }.freeze
+
+      # Batch upload result: the session to poll, the parts sent and the name→{fileSize, fileHash}
+      # map of the invoices inside (to correlate per-invoice statuses).
+      Result = Struct.new(:reference_number, :parts, :files, keyword_init: true)
+
+      # @param client [Ksef::Client]
+      # @param part_size [Integer] maximum plaintext part size, up to {Splitter::MAX_PART_SIZE}
+      # @raise [Ksef::ConfigurationError] for a part size outside 1..{Splitter::MAX_PART_SIZE}
+      def initialize(client, part_size: Splitter::DEFAULT_PART_SIZE)
+        @client = client
+        @splitter = Splitter.new(crypto: client.crypto, part_size: part_size)
+      end
+
+      # Runs the full batch upload.
+      #
+      # @param invoices [Hash{String=>String}, Array<String>] invoice XML
+      # @param form_code [Ksef::FormCode, Hash]
+      # @param encryption [Ksef::Crypto::CryptographyService::EncryptionData, nil]
+      # @param offline_mode [Boolean]
+      # @param compression [Symbol] :zip (default) or :tar_gz
+      # @return [Result]
+      # @raise [Ksef::ConfigurationError] for no invoices, names that collide in the package, a tar entry name
+      #   over {PackageBuilder::TAR_NAME_LIMIT} bytes, or a package over the contract limits — before
+      #   anything is sent
+      # @raise [Ksef::BatchUploadError] when a part cannot be uploaded or the session cannot be closed
+      def call(invoices:, form_code: FormCode::FA3, encryption: nil, offline_mode: false, compression: :zip)
+        package = build_package(invoices, compression)
+        check_limits!(package.bytes.bytesize)
+        enc = encryption || @client.crypto.encryption_data
+        split = @splitter.split(package.bytes, enc)
+        batch_file = split.batch_file.merge("compressionType" => COMPRESSION_TYPES.fetch(compression))
+
+        # After a key rotation (21470) the same key is wrapped under the new certificate, so the
+        # parts' ciphertext and hashes stay valid.
+        response = @client.public_keys.with_rotation_retry do |retrying|
+          enc = @client.crypto.rewrap(enc) if retrying
+          @client.batch.open(form_code: form_code, batch_file: batch_file,
+                             encryption_info: enc.encryption_info, offline_mode: offline_mode)
+        end
+        reference_number = response["referenceNumber"]
+        upload_parts(reference_number, response["partUploadRequests"], split.parts) do |part|
+          @splitter.encrypt(package.bytes, part, enc)
+        end
+        close_session(reference_number)
+
+        Result.new(reference_number: reference_number, parts: split.parts, files: package.files)
+      end
+
+      private
+
+      def build_package(invoices, compression)
+        case compression
+        when :zip then PackageBuilder.zip(invoices)
+        when :tar_gz then PackageBuilder.tar_gz(invoices)
+        else raise ConfigurationError, "Unknown compression type: #{compression.inspect} (:zip or :tar_gz)"
+        end
+      end
+
+      def check_limits!(size)
+        if size > MAX_PACKAGE_SIZE
+          raise ConfigurationError, "the package has #{size} bytes; KSeF accepts at most #{MAX_PACKAGE_SIZE}"
+        end
+
+        parts = @splitter.part_count(size)
+        return if parts <= MAX_PARTS
+
+        raise ConfigurationError, "the package needs #{parts} parts; KSeF accepts at most #{MAX_PARTS} " \
+                                  "(raise part_size, up to #{Splitter::MAX_PART_SIZE})"
+      end
+
+      # Uploads every part to its presigned URL, sequentially; the block returns a part's ciphertext.
+      def upload_parts(reference_number, upload_requests, parts)
+        requests = Array(upload_requests).to_h { |request| [request["ordinalNumber"], request] }
+        declared = parts.map(&:ordinal_number)
+        unless requests.size == declared.size && (declared - requests.keys).empty?
+          raise BatchUploadError.new("upload URLs do not match the declared parts " \
+                                     "(declared #{declared.inspect}, got #{requests.keys.inspect})",
+                                     reference_number: reference_number)
+        end
+
+        parts.each do |part|
+          request = requests.fetch(part.ordinal_number)
+          @client.connection.presigned_transfer(request["method"] || "PUT", request["url"],
+                                                body: yield(part), headers: request["headers"] || {})
+        rescue Error => e
+          raise BatchUploadError.new("part #{part.ordinal_number} upload failed: #{e.message}",
+                                     reference_number: reference_number, ordinal_number: part.ordinal_number)
+        end
+      end
+
+      # Close is a POST, so a 5xx or a timeout is not retried — the error keeps the session reference so
+      # the caller can check its status and close it again.
+      def close_session(reference_number)
+        @client.batch.close(reference_number)
+      rescue Error => e
+        raise BatchUploadError.new("closing the session failed: #{e.message}", reference_number: reference_number)
+      end
+    end
+  end
+end

data/lib/ksef/client.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Ksef
+  # KSeF client facade: configuration, HTTP connection and an optional access
+  # token, delegating to 14 domain resources and the cryptography services.
+  #
+  # `access_token` is per-client state, never global (a callable is read on every request); auth
+  # endpoints take their own tokens explicitly through {Ksef::Auth::Coordinator}. The configuration is
+  # copied when the client is built, so a later {Ksef.configure} cannot split its environment.
+  class Client
+    # @return [Ksef::Configuration] this client's copy of the configuration
+    attr_reader :config
+    # @return [Ksef::Http::Connection]
+    attr_reader :connection
+    # @return [Ksef::Crypto::PublicKeys] cache of the Ministry of Finance public-key certificates
+    attr_reader :public_keys
+    # @return [Ksef::Crypto::CryptographyService]
+    attr_reader :crypto
+    # Replaces the default token (a String or a callable). On a client shared between threads use
+    # {#with_access_token} instead — this mutates every caller's client.
+    attr_writer :access_token
+
+    # @param access_token [String, #call, nil] the accessToken, or a callable returning the current one
+    #   (e.g. `-> { manager.access_token }` with a {Ksef::TokenManager})
+    # @param config [Ksef::Configuration, nil] defaults to the global configuration {Ksef.config}; copied
+    # @param connection [Ksef::Http::Connection, nil] injectable (for tests)
+    # @param public_keys [Ksef::Crypto::PublicKeys, nil] a key cache to share (see {#with_access_token})
+    def initialize(access_token: nil, config: nil, connection: nil, public_keys: nil)
+      @config = (config || Ksef.config).with
+      @access_token = access_token
+      @connection = connection || Http::Connection.new(config: @config)
+      @public_keys = public_keys || Crypto::PublicKeys.new(connection: @connection, logger: @config.logger)
+      @crypto = Crypto::CryptographyService.new(public_keys: @public_keys)
+    end
+
+    # @return [String, nil] the access token the resources send by default
+    def access_token
+      @access_token.respond_to?(:call) ? @access_token.call : @access_token
+    end
+
+    # A copy of the client with a different access token, sharing the connection and the key cache —
+    # the way to serve many contexts from one client (the original is not mutated).
+    # @param token [String, #call]
+    # @return [Client]
+    def with_access_token(token)
+      self.class.new(access_token: token, config: @config, connection: @connection, public_keys: @public_keys)
+    end
+
+    # Closes the keep-alive connections (shared with the clients from {#with_access_token}); a later
+    # request opens new ones.
+    # @return [void]
+    def close
+      @connection.close
+    end
+
+    # Keeps the access token out of error pages, `pp` output and exception reports.
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} environment=#{@config.environment.inspect} " \
+        "access_token=#{@access_token ? '[REDACTED]' : 'nil'}>"
+    end
+
+    # --- domain resources (1:1 with endpoints) ---
+
+    # @return [Ksef::Resources::Auth] /auth/*
+    def auth
+      @auth ||= Resources::Auth.new(self)
+    end
+
+    # @return [Ksef::Resources::Sessions] session reads/status: GET /sessions*
+    def sessions
+      @sessions ||= Resources::Sessions.new(self)
+    end
+
+    # @return [Ksef::Resources::OnlineSessions] POST /sessions/online*
+    def online
+      @online ||= Resources::OnlineSessions.new(self)
+    end
+
+    # @return [Ksef::Resources::BatchSessions] POST /sessions/batch*
+    def batch
+      @batch ||= Resources::BatchSessions.new(self)
+    end
+
+    # @return [Ksef::Resources::Invoices] invoice downloads + metadata queries
+    def invoices
+      @invoices ||= Resources::Invoices.new(self)
+    end
+
+    # @return [Ksef::Resources::Exports] invoice package exports
+    def exports
+      @exports ||= Resources::Exports.new(self)
+    end
+
+    # @return [Ksef::Resources::CollectiveIdentifiers] /collective-identifiers*
+    def collective_identifiers
+      @collective_identifiers ||= Resources::CollectiveIdentifiers.new(self)
+    end
+
+    # @return [Ksef::Resources::Certificates] /certificates/*
+    def certificates
+      @certificates ||= Resources::Certificates.new(self)
+    end
+
+    # @return [Ksef::Resources::Tokens] KSeF tokens: /tokens*
+    def tokens
+      @tokens ||= Resources::Tokens.new(self)
+    end
+
+    # @return [Ksef::Resources::Permissions] /permissions/*
+    def permissions
+      @permissions ||= Resources::Permissions.new(self)
+    end
+
+    # @return [Ksef::Resources::Limits] /limits/*, /rate-limits
+    def limits
+      @limits ||= Resources::Limits.new(self)
+    end
+
+    # @return [Ksef::Resources::Security] /security/public-key-certificates
+    def security
+      @security ||= Resources::Security.new(self)
+    end
+
+    # @return [Ksef::Resources::Peppol] /peppol/query
+    def peppol
+      @peppol ||= Resources::Peppol.new(self)
+    end
+
+    # @return [Ksef::Resources::TestData] /testdata/* (TEST only)
+    def test_data
+      @test_data ||= Resources::TestData.new(self)
+    end
+  end
+end

data/lib/ksef/configuration.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "logger"
+require "uri"
+
+module Ksef
+  # Gem configuration: global via {Ksef.configure}, or per client — see {Ksef::Client}.
+  class Configuration
+    # Default timeouts (seconds).
+    DEFAULT_TIMEOUT = 60
+    DEFAULT_OPEN_TIMEOUT = 15
+    # Faraday adapter: keep-alive, so back-to-back calls reuse one TLS connection per host.
+    DEFAULT_ADAPTER = :net_http_persistent
+    # Longest server-requested `Retry-After` (seconds) the client sleeps through on a 429; anything
+    # longer surfaces as {Ksef::RateLimited} so a web worker or job is never parked for hours.
+    DEFAULT_MAX_RETRY_AFTER = 60
+    # Options settable through {#apply} (and Rails `config.ksef.*`).
+    OPTIONS = %i[
+      environment timeout open_timeout proxy logger api_base_url_override qr_base_url_override
+      default_headers prefer_problem_details ksef_features max_retries max_retry_after adapter user_agent
+    ].freeze
+
+    # @return [Symbol] environment key (:test/:demo/:prod)
+    attr_reader :environment
+
+    # @return [Numeric] response timeout (s)
+    attr_reader :timeout
+    # @return [Numeric] connection open timeout (s)
+    attr_reader :open_timeout
+    # @return [String, nil] proxy URL (e.g. "http://proxy.local:3128"); defaults to ENV["KSEF_PROXY"]
+    attr_accessor :proxy
+    # @return [Logger, nil] logger; when nil, logging is disabled
+    attr_accessor :logger
+    # @return [String, nil] override for the API base URL (for tests/mocks)
+    attr_accessor :api_base_url_override
+    # @return [String, nil] override for the QR base URL
+    attr_accessor :qr_base_url_override
+    # @return [Hash{String=>String}] extra headers appended to every request
+    attr_accessor :default_headers
+    # @return [Boolean] whether to send the X-Error-Format: problem-details header (like C#)
+    attr_accessor :prefer_problem_details
+    # @return [Array<String>] feature flags sent in the X-KSeF-Feature header (e.g.
+    #   "subject-identifier-validation"; "upo-v4-3", "include-metadata" and the strict XAdES rules
+    #   are KSeF's default behaviour and need no flag)
+    attr_accessor :ksef_features
+    # @return [Integer] retries per request: a 429 for any call, 500/502/503/504 and network failures for
+    #   idempotent ones (GET, presigned transfers)
+    attr_reader :max_retries
+    # @return [Numeric, nil] upper bound (s) for a `Retry-After` the client honours on a 429; nil — no bound
+    attr_reader :max_retry_after
+    # @return [Symbol, Array] Faraday adapter (plus options), {DEFAULT_ADAPTER} by default — e.g.
+    #   [:net_http_persistent, { pool_size: 5 }], or :net_http to turn keep-alive off
+    attr_accessor :adapter
+    # @return [String] gem User-Agent
+    attr_accessor :user_agent
+
+    # @param environment [Symbol, String, Environments::Environment] defaults to :test
+    def initialize(environment: :test)
+      self.environment = environment
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @proxy = ENV.fetch("KSEF_PROXY", nil)
+      @logger = nil
+      @default_headers = {}
+      @prefer_problem_details = true
+      @ksef_features = []
+      @max_retries = 2
+      @max_retry_after = DEFAULT_MAX_RETRY_AFTER
+      @adapter = DEFAULT_ADAPTER
+      @user_agent = "ksef-ruby/#{Ksef::VERSION}"
+    end
+
+    # @param value [Numeric] seconds, > 0
+    # @raise [Ksef::ConfigurationError]
+    def timeout=(value)
+      @timeout = positive!(:timeout, value)
+    end
+
+    # @param value [Numeric] seconds, > 0
+    # @raise [Ksef::ConfigurationError]
+    def open_timeout=(value)
+      @open_timeout = positive!(:open_timeout, value)
+    end
+
+    # @param value [Integer] >= 0
+    # @raise [Ksef::ConfigurationError]
+    def max_retries=(value)
+      raise ConfigurationError, "max_retries must be an Integer >= 0, got #{value.inspect}" unless
+        value.is_a?(Integer) && value >= 0
+
+      @max_retries = value
+    end
+
+    # @param value [Numeric, nil] seconds, >= 0
+    # @raise [Ksef::ConfigurationError]
+    def max_retry_after=(value)
+      raise ConfigurationError, "max_retry_after must be nil or a number >= 0, got #{value.inspect}" unless
+        value.nil? || (value.is_a?(Numeric) && value >= 0)
+
+      @max_retry_after = value
+    end
+
+    # Sets the environment by key or by {Environments::Environment} object.
+    # @param value [Symbol, String, Environments::Environment]
+    def environment=(value)
+      @env = Environments.fetch(value)
+      @environment = @env.key
+    end
+
+    # @return [Environments::Environment] the resolved environment object
+    attr_reader :env
+
+    # @return [String] base URL for API requests (with the /v2 prefix), honouring the override
+    def api_url
+      base = api_base_url_override || env.api_base_url
+      "#{base.chomp('/')}#{env.api_path_prefix}"
+    end
+
+    # @return [String] base QR URL (without a version prefix)
+    def qr_url
+      (qr_base_url_override || env.qr_base_url).chomp("/")
+    end
+
+    # Assigns every option present in +options+; an unknown key raises, so a typo does not pass silently.
+    # @param options [Hash{Symbol, String => Object}] e.g. Rails `config.ksef`
+    # @return [self]
+    # @raise [Ksef::ConfigurationError] for an unknown option
+    def apply(options)
+      options.each do |name, value|
+        key = name.to_sym
+        unless OPTIONS.include?(key)
+          raise ConfigurationError, "Unknown KSeF option: #{name} (allowed: #{OPTIONS.join(', ')})"
+        end
+
+        public_send("#{key}=", value)
+      end
+      self
+    end
+
+    # A copy with some options changed — e.g. a client for another environment that keeps what the
+    # Railtie or an initializer set. Headers and feature flags are copied; the logger is shared.
+    # @param options [Hash{Symbol, String => Object}] any {OPTIONS} key
+    # @return [Configuration]
+    # @raise [Ksef::ConfigurationError] for an unknown option
+    def with(**options)
+      copy = dup
+      copy.default_headers = default_headers.dup
+      copy.ksef_features = ksef_features.dup
+      copy.apply(options)
+    end
+
+    # Sends `X-KSeF-Feature: enforce-xades-compliance`. Optional: KSeF applies the strict XAdES
+    # validation on every environment with or without it.
+    # @return [self]
+    def enforce_xades_compliance!
+      @ksef_features |= ["enforce-xades-compliance"]
+      self
+    end
+
+    # Keeps a proxy password out of logs, `pp` output and exception reports.
+    # @return [String]
+    def inspect
+      fields = instance_variables.map do |name|
+        value = instance_variable_get(name)
+        value = redacted_proxy(value) if name == :@proxy && value
+        "#{name.to_s.delete_prefix('@')}=#{value.inspect}"
+      end
+      "#<#{self.class.name} #{fields.join(', ')}>"
+    end
+
+    # Builds the invariant headers appended to every request (Authorization aside).
+    # @return [Hash{String=>String}]
+    def base_headers
+      headers = {
+        "User-Agent" => user_agent,
+        "Accept" => "application/json"
+      }
+      headers["X-Error-Format"] = "problem-details" if prefer_problem_details
+      headers["X-KSeF-Feature"] = ksef_features.join(", ") unless ksef_features.empty?
+      headers.merge(default_headers)
+    end
+
+    private
+
+    def positive!(name, value)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ConfigurationError, "#{name} must be a number of seconds > 0, got #{value.inspect}"
+    end
+
+    # Every form Faraday accepts — "scheme://user:pass@host", "user:pass@host", a Hash or ProxyOptions —
+    # shown as scheme://host:port only.
+    def redacted_proxy(value)
+      uri = value.respond_to?(:to_hash) || value.respond_to?(:uri) ? proxy_uri(value) : value.to_s
+      uri = URI.parse(uri.to_s.include?("://") ? uri.to_s : "http://#{uri}")
+      credentials = uri.userinfo || (value.respond_to?(:to_hash) && (value.to_hash[:user] || value.to_hash[:password]))
+      "#{uri.scheme}://#{'[REDACTED]@' if credentials}#{uri.host}#{":#{uri.port}" if uri.port}"
+    rescue URI::InvalidURIError
+      "[REDACTED]"
+    end
+
+    def proxy_uri(value)
+      value.respond_to?(:uri) ? value.uri : (value.to_hash[:uri] || value.to_hash["uri"])
+    end
+  end
+end

data/lib/ksef/crypto/cryptography_service.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "digest"
+
+module Ksef
+  module Crypto
+    # Session cryptography: AES-256-CBC/PKCS#7 with a 16-byte IV, the symmetric key
+    # wrapped with RSA-OAEP SHA-256 + MGF1(SHA-256), hashes SHA-256 in Base64.
+    #
+    # The payload is PLAIN ciphertext WITHOUT an IV prefix — the IV travels only in
+    # EncryptionInfo. Some documentation suggests a prefix; both SDKs send none and the gem follows them.
+    class CryptographyService
+      # Encryption material for one session: key+IV (in the clear) plus {EncryptionInfo} to send.
+      EncryptionData = Struct.new(:key, :iv, :encryption_info, keyword_init: true) do
+        # The session key never goes to error pages, `pp` output or exception reports.
+        # @return [String]
+        def inspect
+          "#<#{self.class.name} key=[REDACTED] iv=[REDACTED] encryption_info=#{encryption_info.inspect}>"
+        end
+        alias_method :to_s, :inspect
+
+        # `pp` and IRB print through #pretty_print, which Struct implements without calling #inspect.
+        def pretty_print(printer)
+          printer.text(inspect)
+        end
+      end
+
+      # Encryption data sent to the API (camelCase fields in JSON).
+      EncryptionInfo = Struct.new(:encrypted_symmetric_key, :initialization_vector, :public_key_id,
+                                  keyword_init: true) do
+        # @return [Hash] JSON representation matching the API contract
+        def to_h
+          {
+            "encryptedSymmetricKey" => encrypted_symmetric_key,
+            "initializationVector" => initialization_vector,
+            "publicKeyId" => public_key_id
+          }.compact
+        end
+      end
+
+      # Digest and size of a file/chunk (hash in Base64).
+      FileMetadata = Struct.new(:size, :hash_sha, keyword_init: true) do
+        # @return [Hash] { "fileSize" => Integer, "fileHash" => Base64 }
+        def to_h
+          { "fileSize" => size, "fileHash" => hash_sha }
+        end
+      end
+
+      # @param public_keys [Ksef::Crypto::PublicKeys]
+      def initialize(public_keys:)
+        @public_keys = public_keys
+      end
+
+      # Session material: a random 256-bit key + 16-byte IV (unless given), the key wrapped under the
+      # current usage=SymmetricKeyEncryption certificate.
+      # @param key [String, nil] 32 B; generated when nil
+      # @param iv [String, nil] 16 B; generated when nil
+      # @return [EncryptionData]
+      def encryption_data(key: nil, iv: nil)
+        key ||= OpenSSL::Random.random_bytes(32)
+        iv ||= OpenSSL::Random.random_bytes(16)
+        cert = @public_keys.for_usage(PublicKeys::SYMMETRIC_KEY_ENCRYPTION)
+        encrypted_key = rsa_oaep_sha256(cert.public_key, key)
+
+        info = EncryptionInfo.new(
+          encrypted_symmetric_key: Base64.strict_encode64(encrypted_key),
+          initialization_vector: Base64.strict_encode64(iv),
+          public_key_id: cert.public_key_id
+        )
+        EncryptionData.new(key: key, iv: iv, encryption_info: info)
+      end
+
+      # The same key and IV wrapped again under the current certificate — after a key rotation
+      # (21470) only EncryptionInfo changes, so data already encrypted with the key stays valid.
+      # @param data [EncryptionData]
+      # @return [EncryptionData]
+      def rewrap(data)
+        encryption_data(key: data.key, iv: data.iv)
+      end
+
+      # Encrypts bytes with AES-256-CBC/PKCS7. Returns PLAIN ciphertext without an IV prefix.
+      # @param content [String] plaintext bytes
+      # @param key [String] 32 B
+      # @param iv [String] 16 B
+      # @return [String] ciphertext (bytes)
+      def encrypt_aes(content, key, iv)
+        cipher = OpenSSL::Cipher.new("aes-256-cbc")
+        cipher.encrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.update(content) << cipher.final # appended in place: a part is up to 100 MB
+      end
+
+      # Decrypts AES-256-CBC/PKCS7 bytes (ciphertext without an IV prefix; IV from EncryptionInfo).
+      # @param content [String] ciphertext
+      # @param key [String] 32 B
+      # @param iv [String] 16 B
+      # @return [String] plaintext bytes
+      # @raise [Ksef::CryptoError] when the data does not decrypt (wrong key/IV or corrupted bytes)
+      def decrypt_aes(content, key, iv)
+        cipher = OpenSSL::Cipher.new("aes-256-cbc")
+        cipher.decrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.update(content) << cipher.final
+      rescue OpenSSL::Cipher::CipherError => e
+        raise CryptoError, "AES decryption failed: #{e.message}"
+      end
+
+      # Encrypts data with RSA-OAEP using SHA-256 and MGF1(SHA-256).
+      # @param public_key [OpenSSL::PKey::RSA]
+      # @param data [String]
+      # @return [String] ciphertext (bytes)
+      def rsa_oaep_sha256(public_key, data)
+        public_key.encrypt(
+          data,
+          rsa_padding_mode: "oaep",
+          rsa_oaep_md: "sha256",
+          rsa_mgf1_md: "sha256"
+        )
+      end
+
+      # Computes the SHA-256 digest (Base64) and the byte size.
+      # @param bytes [String]
+      # @return [FileMetadata]
+      def metadata(bytes)
+        FileMetadata.new(
+          size: bytes.bytesize,
+          hash_sha: Base64.strict_encode64(Digest::SHA256.digest(bytes))
+        )
+      end
+    end
+  end
+end