ksef-client-rails 0.1.0 → 1.0.0

data/examples/fa3_full.xml

@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
+  <Naglowek>
+    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
+    <WariantFormularza>3</WariantFormularza>
+    <DataWytworzeniaFa>2026-02-01T10:00:00Z</DataWytworzeniaFa>
+    <SystemInfo>ksef-client-rails</SystemInfo>
+  </Naglowek>
+  <Podmiot1>
+    <DaneIdentyfikacyjne>
+      <NIP>5555555555</NIP>
+      <Nazwa>Seller Ltd.</Nazwa>
+    </DaneIdentyfikacyjne>
+    <Adres>
+      <KodKraju>PL</KodKraju>
+      <AdresL1>1 Test Street, 00-001 Warsaw</AdresL1>
+    </Adres>
+    <DaneKontaktowe>
+      <Email>invoices@seller.example</Email>
+      <Telefon>+48 22 000 00 00</Telefon>
+    </DaneKontaktowe>
+  </Podmiot1>
+  <Podmiot2>
+    <DaneIdentyfikacyjne>
+      <NIP>1111111111</NIP>
+      <Nazwa>Buyer Inc.</Nazwa>
+    </DaneIdentyfikacyjne>
+    <Adres>
+      <KodKraju>PL</KodKraju>
+      <AdresL1>2 Example Street, 00-002 Warsaw</AdresL1>
+    </Adres>
+    <DaneKontaktowe>
+      <Email>accounts@buyer.example</Email>
+    </DaneKontaktowe>
+    <JST>2</JST>
+    <GV>2</GV>
+  </Podmiot2>
+  <Fa>
+    <KodWaluty>PLN</KodWaluty>
+    <P_1>2026-02-01</P_1>
+    <P_1M>Warsaw</P_1M>
+    <P_2>FV/2026/02/1</P_2>
+    <P_6>2026-02-01</P_6>
+    <P_13_1>1900.00</P_13_1>
+    <P_14_1>437.00</P_14_1>
+    <P_13_2>120.00</P_13_2>
+    <P_14_2>9.60</P_14_2>
+    <P_13_3>50.00</P_13_3>
+    <P_14_3>2.50</P_14_3>
+    <P_13_6_1>20.00</P_13_6_1>
+    <P_13_7>30.00</P_13_7>
+    <P_15>2569.10</P_15>
+    <Adnotacje>
+      <P_16>2</P_16>
+      <P_17>2</P_17>
+      <P_18>2</P_18>
+      <P_18A>2</P_18A>
+      <Zwolnienie>
+        <P_19>1</P_19>
+        <P_19A>Art. 43 ust. 1 pkt 37 ustawy o VAT</P_19A>
+      </Zwolnienie>
+      <NoweSrodkiTransportu>
+        <P_22N>1</P_22N>
+      </NoweSrodkiTransportu>
+      <P_23>2</P_23>
+      <PMarzy>
+        <P_PMarzyN>1</P_PMarzyN>
+      </PMarzy>
+    </Adnotacje>
+    <RodzajFaktury>VAT</RodzajFaktury>
+    <FaWiersz>
+      <NrWierszaFa>1</NrWierszaFa>
+      <P_7>Software licence</P_7>
+      <Indeks>LIC-01</Indeks>
+      <GTIN>5901234123457</GTIN>
+      <PKWiU>58.29.50.0</PKWiU>
+      <CN>8523</CN>
+      <P_8A>szt.</P_8A>
+      <P_8B>2</P_8B>
+      <P_9A>1000.00</P_9A>
+      <P_10>100.00</P_10>
+      <P_11>1900.00</P_11>
+      <P_12>23</P_12>
+      <GTU>GTU_12</GTU>
+    </FaWiersz>
+    <FaWiersz>
+      <NrWierszaFa>2</NrWierszaFa>
+      <P_7>Printed manual</P_7>
+      <P_8A>szt.</P_8A>
+      <P_8B>1</P_8B>
+      <P_9A>50.00</P_9A>
+      <P_11>50.00</P_11>
+      <P_12>5</P_12>
+    </FaWiersz>
+    <FaWiersz>
+      <NrWierszaFa>3</NrWierszaFa>
+      <P_7>Catering</P_7>
+      <P_8A>szt.</P_8A>
+      <P_8B>3</P_8B>
+      <P_9A>40.00</P_9A>
+      <P_11>120.00</P_11>
+      <P_12>8</P_12>
+    </FaWiersz>
+    <FaWiersz>
+      <NrWierszaFa>4</NrWierszaFa>
+      <P_7>Zero-rated supply</P_7>
+      <P_8A>szt.</P_8A>
+      <P_8B>1</P_8B>
+      <P_9A>20.00</P_9A>
+      <P_11>20.00</P_11>
+      <P_12>0 KR</P_12>
+    </FaWiersz>
+    <FaWiersz>
+      <NrWierszaFa>5</NrWierszaFa>
+      <P_7>Insurance</P_7>
+      <P_8A>szt.</P_8A>
+      <P_8B>1</P_8B>
+      <P_9A>30.00</P_9A>
+      <P_11>30.00</P_11>
+      <P_12>zw</P_12>
+    </FaWiersz>
+    <Platnosc>
+      <TerminPlatnosci>
+        <Termin>2026-02-15</Termin>
+      </TerminPlatnosci>
+      <FormaPlatnosci>6</FormaPlatnosci>
+      <RachunekBankowy>
+        <NrRB>17100000000000000000000001</NrRB>
+        <NazwaBanku>Example Bank</NazwaBanku>
+      </RachunekBankowy>
+    </Platnosc>
+  </Fa>
+  <Stopka>
+    <Informacje>
+      <StopkaFaktury>Thank you for your business.</StopkaFaktury>
+    </Informacje>
+    <Rejestry>
+      <KRS>0000123456</KRS>
+      <REGON>123456785</REGON>
+      <BDO>000012345</BDO>
+    </Rejestry>
+  </Stopka>
+</Faktura>

data/examples/fa3_minimal.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
+  <Naglowek>
+    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
+    <WariantFormularza>3</WariantFormularza>
+    <DataWytworzeniaFa>2026-02-01T10:00:00Z</DataWytworzeniaFa>
+    <SystemInfo>ksef-client-rails</SystemInfo>
+  </Naglowek>
+  <Podmiot1>
+    <DaneIdentyfikacyjne>
+      <NIP>5555555555</NIP>
+      <Nazwa>Seller Ltd.</Nazwa>
+    </DaneIdentyfikacyjne>
+    <Adres>
+      <KodKraju>PL</KodKraju>
+      <AdresL1>1 Test Street, 00-001 Warsaw</AdresL1>
+    </Adres>
+  </Podmiot1>
+  <Podmiot2>
+    <DaneIdentyfikacyjne>
+      <NIP>1111111111</NIP>
+      <Nazwa>Buyer Inc.</Nazwa>
+    </DaneIdentyfikacyjne>
+    <Adres>
+      <KodKraju>PL</KodKraju>
+      <AdresL1>2 Example Street, 00-002 Warsaw</AdresL1>
+    </Adres>
+    <JST>2</JST>
+    <GV>2</GV>
+  </Podmiot2>
+  <Fa>
+    <KodWaluty>PLN</KodWaluty>
+    <P_1>2026-02-01</P_1>
+    <P_2>FV/2026/02/1</P_2>
+    <P_13_1>100.00</P_13_1>
+    <P_14_1>23.00</P_14_1>
+    <P_15>123.00</P_15>
+    <Adnotacje>
+      <P_16>2</P_16>
+      <P_17>2</P_17>
+      <P_18>2</P_18>
+      <P_18A>2</P_18A>
+      <Zwolnienie>
+        <P_19N>1</P_19N>
+      </Zwolnienie>
+      <NoweSrodkiTransportu>
+        <P_22N>1</P_22N>
+      </NoweSrodkiTransportu>
+      <P_23>2</P_23>
+      <PMarzy>
+        <P_PMarzyN>1</P_PMarzyN>
+      </PMarzy>
+    </Adnotacje>
+    <RodzajFaktury>VAT</RodzajFaktury>
+    <FaWiersz>
+      <NrWierszaFa>1</NrWierszaFa>
+      <P_7>Demo service</P_7>
+      <P_8A>szt.</P_8A>
+      <P_8B>1</P_8B>
+      <P_9A>100.00</P_9A>
+      <P_11>100.00</P_11>
+      <P_12>23</P_12>
+    </FaWiersz>
+  </Fa>
+</Faktura>

data/examples/fa3_typical.xml

@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
+  <Naglowek>
+    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
+    <WariantFormularza>3</WariantFormularza>
+    <DataWytworzeniaFa>2026-02-01T10:00:00Z</DataWytworzeniaFa>
+    <SystemInfo>ksef-client-rails</SystemInfo>
+  </Naglowek>
+  <Podmiot1>
+    <DaneIdentyfikacyjne>
+      <NIP>5555555555</NIP>
+      <Nazwa>Seller Ltd.</Nazwa>
+    </DaneIdentyfikacyjne>
+    <Adres>
+      <KodKraju>PL</KodKraju>
+      <AdresL1>1 Test Street, 00-001 Warsaw</AdresL1>
+    </Adres>
+  </Podmiot1>
+  <Podmiot2>
+    <DaneIdentyfikacyjne>
+      <NIP>1111111111</NIP>
+      <Nazwa>Buyer Inc.</Nazwa>
+    </DaneIdentyfikacyjne>
+    <Adres>
+      <KodKraju>PL</KodKraju>
+      <AdresL1>2 Example Street, 00-002 Warsaw</AdresL1>
+    </Adres>
+    <JST>2</JST>
+    <GV>2</GV>
+  </Podmiot2>
+  <Fa>
+    <KodWaluty>PLN</KodWaluty>
+    <P_1>2026-02-01</P_1>
+    <P_1M>Warsaw</P_1M>
+    <P_2>FV/2026/02/1</P_2>
+    <P_6>2026-02-01</P_6>
+    <P_13_1>100.00</P_13_1>
+    <P_14_1>23.00</P_14_1>
+    <P_15>123.00</P_15>
+    <Adnotacje>
+      <P_16>2</P_16>
+      <P_17>2</P_17>
+      <P_18>2</P_18>
+      <P_18A>2</P_18A>
+      <Zwolnienie>
+        <P_19N>1</P_19N>
+      </Zwolnienie>
+      <NoweSrodkiTransportu>
+        <P_22N>1</P_22N>
+      </NoweSrodkiTransportu>
+      <P_23>2</P_23>
+      <PMarzy>
+        <P_PMarzyN>1</P_PMarzyN>
+      </PMarzy>
+    </Adnotacje>
+    <RodzajFaktury>VAT</RodzajFaktury>
+    <FaWiersz>
+      <NrWierszaFa>1</NrWierszaFa>
+      <P_7>Demo service</P_7>
+      <P_8A>szt.</P_8A>
+      <P_8B>1</P_8B>
+      <P_9A>100.00</P_9A>
+      <P_11>100.00</P_11>
+      <P_12>23</P_12>
+    </FaWiersz>
+    <Platnosc>
+      <TerminPlatnosci>
+        <Termin>2026-02-15</Termin>
+      </TerminPlatnosci>
+      <FormaPlatnosci>6</FormaPlatnosci>
+      <RachunekBankowy>
+        <NrRB>17100000000000000000000001</NrRB>
+      </RachunekBankowy>
+    </Platnosc>
+  </Fa>
+</Faktura>

data/lib/generators/ksef/install/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Ksef
+  module Generators
+    # Install generator: `rails g ksef:install`.
+    # Creates `config/initializers/ksef.rb` with pointers to Rails credentials.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the KSeF initializer at config/initializers/ksef.rb"
+
+      # Copies the initializer template into the application.
+      def copy_initializer
+        template "ksef.rb", "config/initializers/ksef.rb"
+      end
+    end
+  end
+end

data/lib/generators/ksef/install/templates/ksef.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# KSeF client configuration (the `ksef-client-rails` gem) — https://github.com/CIRFMF/ksef-api
+# Keep the KSeF token and certificates in Rails credentials, never in the repository.
+# This file runs after `config.ksef.*` from config/application.rb (railtie), so whatever it sets wins.
+
+Ksef.configure do |config|
+  # Environment: :test | :demo | :prod — set it explicitly for every deployment. Never derive it from
+  # Rails.env: staging usually runs with RAILS_ENV=production, and every invoice sent to :prod is
+  # legally binding. Without KSEF_ENV (or with it empty) the environment stays as configured (default :test).
+  config.environment = ENV["KSEF_ENV"].presence || config.environment
+
+  # Timeouts in seconds (defaults: 60 and 15):
+  # config.timeout = 60
+  # config.open_timeout = 15
+
+  # The railtie logs to Rails.logger; nil turns logging off:
+  # config.logger = nil
+
+  # A 429 asking to wait longer than this (seconds) raises Ksef::RateLimited instead of sleeping:
+  # config.max_retry_after = 60
+
+  # API feature flags sent as X-KSeF-Feature (e.g. "subject-identifier-validation" on TEST/DEMO):
+  # config.ksef_features = %w[]
+end

data/lib/ksef/auth/coordinator.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # Authentication coordinator: orchestrates the full flow
+    # challenge → signature|token → POST → polling GET /auth/{ref} → redeem → (refresh).
+    #
+    # Polling returns `status.code` inside a 200 body (NOT an HTTP code): 100 in progress,
+    # 200 OK, everything else is an error — see {Ksef::AuthenticationFailed}.
+    class Coordinator
+      # The "operation in progress" code.
+      STATUS_IN_PROGRESS = 100
+      # The "authenticated" code.
+      STATUS_SUCCESS = 200
+
+      # Context key → AuthenticationContextIdentifierType enum value (PascalCase).
+      CONTEXT_TYPES = {
+        nip: "Nip",
+        internal_id: "InternalId",
+        nip_vat_ue: "NipVatUe",
+        peppol_id: "PeppolId"
+      }.freeze
+
+      # Authentication result: the token pair plus the auth session reference number.
+      Result = Struct.new(:reference_number, :access_token, :access_token_valid_until,
+                          :refresh_token, :refresh_token_valid_until, keyword_init: true) do
+        # Tokens never go to error pages, `pp` output or exception reports.
+        # @return [String]
+        def inspect
+          "#<#{self.class.name} reference_number=#{reference_number.inspect} " \
+            "access_token=[REDACTED] access_token_valid_until=#{access_token_valid_until.inspect} " \
+            "refresh_token=[REDACTED] refresh_token_valid_until=#{refresh_token_valid_until.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
+
+      # @param client [Ksef::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      # Authenticates with an XAdES signature (local certificate or an external signer).
+      #
+      # @param context [Hash] one of {nip:}, {internal_id:}, {nip_vat_ue:}, {peppol_id:}; a NIP is
+      #   normalized ({Ksef::Nip.normalize!}) and an invalid one raises Ksef::ConfigurationError
+      # @param signer [#sign, #call] {Ksef::Xades::Signer} or a lambda signing the XML
+      # @param subject_identifier_type [Symbol] :certificate_subject|:certificate_fingerprint
+      # @param allowed_ips [Hash, nil] {addresses:, ranges:, masks:}
+      # @param verify_certificate_chain [Boolean]
+      # @param poll [Hash] polling options (timeout:, interval:, ...)
+      # @return [Result]
+      # @raise [Ksef::ConfigurationError] for an invalid context, subject type, allowed_ips or signer — before
+      #   any request
+      def authenticate(context:, signer:, subject_identifier_type: :certificate_subject,
+                       allowed_ips: nil, verify_certificate_chain: false, poll: {})
+        signer = Xades::ExternalSigner.wrap(signer) # an unusable signer fails before any request
+        request = Xades::AuthTokenRequest.new(context: context, subject_identifier_type: subject_identifier_type,
+                                              allowed_ips: allowed_ips)
+        request.challenge = @client.auth.challenge["challenge"]
+        signed = Xades::ExternalSigner.signed!(signer.sign(request.to_xml))
+        init = @client.auth.submit_xades(signed, verify_certificate_chain: verify_certificate_chain)
+        finalize(init, poll)
+      end
+
+      # Authenticates with an encrypted KSeF token (RSA-OAEP).
+      #
+      # @param context [Hash] one of {nip:}, {internal_id:}, {nip_vat_ue:}, {peppol_id:}; a NIP is
+      #   normalized ({Ksef::Nip.normalize!}) and an invalid one raises Ksef::ConfigurationError
+      # @param token [String] KSeF token (secret)
+      # @param poll [Hash] polling options
+      # @return [Result]
+      def authenticate_with_token(context:, token:, poll: {})
+        type, value = context_type_and_value(context)
+        encryptor = KsefTokenEncryptor.new(crypto: @client.crypto, public_keys: @client.public_keys)
+        # A retry after key rotation starts over with a fresh challenge.
+        init = @client.public_keys.with_rotation_retry do
+          challenge = @client.auth.challenge
+          encrypted = encryptor.encrypt(token: token, timestamp_ms: challenge["timestampMs"])
+          @client.auth.submit_ksef_token(
+            challenge: challenge["challenge"],
+            context_type: type,
+            context_value: value,
+            encrypted_token: encrypted.encrypted_token,
+            public_key_id: encrypted.public_key_id
+          )
+        end
+        finalize(init, poll)
+      end
+
+      # Refreshes the accessToken using the refresh token.
+      # @param refresh_token [String]
+      # @return [Hash] { "accessToken" => {token, validUntil} }
+      def refresh(refresh_token:)
+        @client.auth.refresh(refresh_token: refresh_token)
+      end
+
+      private
+
+      def finalize(init, poll_opts)
+        reference_number = init["referenceNumber"]
+        auth_token = token!(init, "authenticationToken", "the authentication init")
+        wait_until_authenticated(reference_number, auth_token, poll_opts)
+
+        tokens = @client.auth.redeem(authentication_token: auth_token)
+        Result.new(
+          reference_number: reference_number,
+          access_token: token!(tokens, "accessToken", "POST /auth/token/redeem"),
+          access_token_valid_until: tokens.dig("accessToken", "validUntil"),
+          refresh_token: token!(tokens, "refreshToken", "POST /auth/token/redeem"),
+          refresh_token_valid_until: tokens.dig("refreshToken", "validUntil")
+        )
+      end
+
+      def token!(response, key, operation)
+        token = response[key].is_a?(Hash) ? response[key]["token"] : nil
+        return token unless token.to_s.empty?
+
+        raise ApiError, "#{operation}: KSeF's response lacks #{key}.token"
+      end
+
+      def wait_until_authenticated(reference_number, auth_token, poll_opts)
+        Polling.run(description: "auth #{reference_number}", logger: @client.config.logger, **poll_opts) do
+          response = @client.auth.status(reference_number, authentication_token: auth_token)
+          interpret_status(response)
+        end
+      end
+
+      def interpret_status(response)
+        status = response["status"] || {}
+        case status["code"]
+        when STATUS_IN_PROGRESS
+          Polling.pending
+        when STATUS_SUCCESS
+          response
+        else
+          raise AuthenticationFailed.new(
+            status["description"] || "Authentication failed",
+            code: status["code"],
+            messages: status["details"]
+          )
+        end
+      end
+
+      def context_type_and_value(context)
+        unless context.is_a?(Hash)
+          raise ConfigurationError, "context must be a Hash with exactly one of: #{CONTEXT_TYPES.keys.join(', ')}"
+        end
+
+        pairs = context.transform_keys(&:to_sym)
+        key, value = pairs.first
+        unless pairs.size == 1 && CONTEXT_TYPES.key?(key)
+          raise ConfigurationError, "context must contain exactly one of: #{CONTEXT_TYPES.keys.join(', ')}"
+        end
+
+        [CONTEXT_TYPES.fetch(key), key == :nip ? Nip.normalize!(value, name: "context nip") : value.to_s]
+      end
+    end
+  end
+end

data/lib/ksef/auth/ksef_token_encryptor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Ksef
+  module Auth
+    # Encrypts the KSeF token for token authentication: `"#{token}|#{timestampMs}"`
+    # wrapped with RSA-OAEP(SHA-256), Base64. The timestamp must come from `/auth/challenge`
+    # (epoch MILLISECONDS), never the local clock. ECIES is out of scope: undocumented in the API
+    # docs and assembled incompatibly between the two SDKs.
+    class KsefTokenEncryptor
+      # @param crypto [Ksef::Crypto::CryptographyService]
+      # @param public_keys [Ksef::Crypto::PublicKeys]
+      def initialize(crypto:, public_keys:)
+        @crypto = crypto
+        @public_keys = public_keys
+      end
+
+      # Encryption result: Base64 token + public key identifier.
+      Result = Struct.new(:encrypted_token, :public_key_id, keyword_init: true)
+
+      # @param token [String] KSeF token (secret)
+      # @param timestamp_ms [Integer] timestampMs from /auth/challenge
+      # @return [Result]
+      def encrypt(token:, timestamp_ms:)
+        cert = @public_keys.for_usage(Crypto::PublicKeys::KSEF_TOKEN_ENCRYPTION)
+        payload = "#{token}|#{timestamp_ms}"
+        ciphertext = @crypto.rsa_oaep_sha256(cert.public_key, payload)
+        Result.new(
+          encrypted_token: Base64.strict_encode64(ciphertext),
+          public_key_id: cert.public_key_id
+        )
+      end
+    end
+  end
+end

data/lib/ksef/batch/package_builder.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Ksef
+  module Batch
+    # Builds the batch package (ZIP or tar.gz) plus a local hash→file map for correlating statuses.
+    # File names stay local — `BatchFilePartInfo` has no `fileName`. A tar entry name must fit the
+    # 100-byte USTAR name field: a longer one would need a GNU long-name record, which KSeF is not known to read.
+    class PackageBuilder
+      # The built package: raw (plaintext) bytes + a name→{hash,size} map of the files inside, keyed by
+      # the name in the package.
+      Package = Struct.new(:bytes, :files, keyword_init: true) do
+        # The package size and file count — never its bytes.
+        # @return [String]
+        def inspect
+          "#<#{self.class.name} bytes=#{bytes.to_s.bytesize} files=#{files.to_h.size}>"
+        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
+
+      # Longest tar entry name, in bytes (the USTAR `name` field).
+      TAR_NAME_LIMIT = 100
+
+      # ZIP general-purpose flag bit 11 (APPNOTE 4.4.4): the entry name is UTF-8. rubyzip sets it only
+      # under the global `Zip.unicode_names`, which would change rubyzip for the whole process.
+      UTF8_NAME_FLAG = 0x0800
+
+      # Builds a ZIP package.
+      # @param invoices [Hash{String=>String}, Array<String>] invoices (name→XML or a list of XML)
+      # @return [Package]
+      # @raise [Ksef::ConfigurationError] for no invoices, or two names that are the same in the package
+      def self.zip(invoices)
+        require "zip"
+        named = normalize(invoices)
+        buffer = Zip::OutputStream.write_buffer do |zos|
+          named.each do |name, xml|
+            zos.put_next_entry(zip_entry(name))
+            zos.write(xml)
+          end
+        end
+        Package.new(bytes: buffer.string, files: files_map(named))
+      end
+
+      # Builds a tar.gz package (requires the `minitar` gem).
+      # @param invoices [Hash{String=>String}, Array<String>]
+      # @return [Package]
+      # @raise [Ksef::ConfigurationError] when minitar is not installed, for no invoices, two names that are
+      #   the same in the package, or a name over {TAR_NAME_LIMIT} bytes
+      def self.tar_gz(invoices)
+        Ksef.require_optional("minitar", "A tar.gz package")
+        require "zlib"
+        named = normalize(invoices)
+        too_long = named.keys.select { |name| name.bytesize > TAR_NAME_LIMIT }
+        unless too_long.empty?
+          raise ConfigurationError, "tar entry names are limited to #{TAR_NAME_LIMIT} bytes: #{too_long.join(', ')}"
+        end
+
+        Package.new(bytes: tar_bytes(named), files: files_map(named))
+      end
+
+      def self.tar_bytes(named)
+        io = StringIO.new("".b)
+        Zlib::GzipWriter.wrap(io) do |gz|
+          Minitar::Writer.open(gz) do |tar|
+            named.each do |name, xml|
+              tar.add_file_simple(name.b, mode: 0o644, size: xml.bytesize) { |stream| stream.write(xml) }
+            end
+          end
+        end
+        io.string
+      end
+
+      def self.zip_entry(name)
+        entry = Zip::Entry.new("", name)
+        entry.gp_flags |= UTF8_NAME_FLAG unless name.ascii_only?
+        entry
+      end
+
+      # Normalizes the input into a name→XML map with the names as they go into the package: UTF-8, with
+      # `/` for a backslash (auto-generated names for a list).
+      def self.normalize(invoices)
+        raise ConfigurationError, "a batch package needs at least one invoice" if invoices.nil? || invoices.empty?
+        return invoices.each_with_index.to_h { |xml, i| [format("invoice-%04d.xml", i + 1), xml] } unless
+          invoices.is_a?(Hash)
+
+        named = invoices.to_h { |name, xml| [package_name(name), xml] }
+        return named if named.size == invoices.size
+
+        duplicates = invoices.keys.group_by { |name| package_name(name) }.select { |_, keys| keys.size > 1 }
+        raise ConfigurationError, "invoice names collide in the package: #{duplicates.values.map(&:inspect).join('; ')}"
+      end
+
+      def self.package_name(name)
+        text = name.to_s
+        text = text.encode(Encoding::UTF_8) unless text.encoding == Encoding::UTF_8
+        raise ConfigurationError, "invoice name #{text.inspect} is not valid UTF-8" unless text.valid_encoding?
+        raise ConfigurationError, "invoice names must not be blank" if text.strip.empty?
+
+        name = text.tr("\\", "/")
+        return name unless name.start_with?("/") || name.split("/").include?("..")
+
+        raise ConfigurationError, "invoice name #{text.inspect} must not be absolute or contain a .. segment"
+      rescue EncodingError
+        raise ConfigurationError, "invoice name #{name.inspect} cannot be converted to UTF-8"
+      end
+
+      def self.files_map(named)
+        require "digest"
+        require "base64"
+        named.transform_values do |xml|
+          bytes = xml.b
+          { "fileSize" => bytes.bytesize, "fileHash" => Base64.strict_encode64(Digest::SHA256.digest(bytes)) }
+        end
+      end
+
+      private_class_method :tar_bytes, :zip_entry, :normalize, :package_name, :files_map
+    end
+  end
+end