ksef_client 0.1.0.rc1 → 0.1.0

data/lib/ksef/crypto/digest.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Crypto
+    # The SHA-256-and-size pair KSeF wants beside a payload (docs/REFERENCE.md §11.1).
+    #
+    # `POST /sessions/online/{ref}/invoices` carries **four** integrity values — the hash
+    # and size of the plaintext invoice *and* of the ciphertext. Computing one over the
+    # wrong artifact is an easy mistake and a silent one, which is why
+    # {Ksef::Crypto::Encryptor#seal} produces both at once rather than leaving a caller to
+    # pair them up.
+    #
+    # `size` is a **byte** count, not a character count. An invoice full of Polish
+    # characters has more bytes than characters, and reporting the shorter figure would be
+    # rejected downstream.
+    Digest = Data.define(:bytes, :size) do
+      # @param content [String] the exact bytes that will be sent
+      def self.of(content) = new(bytes: Crypto.sha256(content), size: content.bytesize)
+
+      # @return [String] the wire form: base64 of the digest, always 44 characters, which
+      #   is what the contract's `Sha256HashBase64` constrains it to
+      def base64 = Crypto.encode(bytes)
+    end
+  end
+end

data/lib/ksef/crypto/encryptor.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Crypto
+    # A session's symmetric key, and the AES-256-CBC encryption done under it
+    # (docs/REFERENCE.md §10.1).
+    #
+    # ## The IV is not prefixed to the ciphertext
+    #
+    # This is the trap worth knowing about before reading anything else here.
+    # `sesja-interaktywna.md` describes the IV as "dołączanego jako prefiks do szyfrogramu"
+    # — prefixed to the ciphertext. **It is not**, and following that prose produces a
+    # payload KSeF cannot decrypt. The IV travels once, as a discrete field of the
+    # session-open request, and every per-invoice ciphertext is bare. Three higher-precedence
+    # sources agree against the prose, the OpenAPI contract among them (§14.1) — and the
+    # contract's own worked example settles it arithmetically: a 6480-byte invoice becomes
+    # 6496 bytes encrypted. 6480 is a whole number of blocks, so PKCS#7 adds exactly one
+    # block of padding; a prefixed IV would have made it 6512.
+    #
+    # So {#encrypt} returns bare ciphertext, and the IV is exposed separately for the
+    # session-open request via {#encryption_info}.
+    class Encryptor
+      REDACTED = "[REDACTED]"
+
+      # What {#seal} produces: the ciphertext to send, plus the integrity metadata for both
+      # forms of the document. Bundled together because §11.1 requires the hash and size of
+      # the plaintext *and* of the ciphertext, and hashing the wrong one of the two is a
+      # silent error that only the server can detect.
+      Sealed = Data.define(:ciphertext, :plaintext_digest, :ciphertext_digest) do
+        # @return [String] base64 ciphertext, the wire form
+        def content = Crypto.encode(ciphertext)
+      end
+
+      # The IV is not secret — it is sent to the API in the clear — so unlike the key it
+      # has a reader. It is still kept out of {#inspect}, which DESIGN.md §4.5 requires.
+      attr_reader :iv
+
+      # A fresh key and IV from the CSPRNG. §10.1 records a per-session key as
+      # *recommended* by the docs rather than required; recommended is reason enough.
+      def self.generate
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        new(key: cipher.random_key, iv: cipher.random_iv)
+      end
+
+      # @param key [String] 32 raw bytes
+      # @param iv [String] 16 raw bytes
+      # @raise [Ksef::CryptoError] on the wrong length
+      def initialize(key:, iv:)
+        @key = check("key", key, KEY_BYTES)
+        @iv = check("iv", iv, IV_BYTES)
+        freeze
+      end
+
+      # @param plaintext [String] the invoice XML, already serialised. Deliberately not
+      #   `#to_xml`-coercing: what gets hashed has to be exactly what gets encrypted, so
+      #   the bytes are settled one layer up.
+      # @return [String] bare ciphertext, binary — see the class note on the IV
+      def encrypt(plaintext) = transform(:encrypt, plaintext)
+
+      # The inverse. KSeF never asks us to decrypt anything, so this exists for tests and
+      # for a caller wanting to prove to itself that a payload round-trips before sending
+      # it — which beats discovering a key mismatch from a rejected invoice.
+      def decrypt(ciphertext) = transform(:decrypt, ciphertext)
+
+      # Encrypt once, and measure both artifacts while they are in hand.
+      #
+      # @param plaintext [String]
+      # @return [Sealed]
+      def seal(plaintext)
+        ciphertext = encrypt(plaintext)
+        Sealed.new(
+          ciphertext: ciphertext,
+          plaintext_digest: Digest.of(plaintext),
+          ciphertext_digest: Digest.of(ciphertext)
+        )
+      end
+
+      # The contract's `EncryptionInfo`, as sent on `POST /sessions/online`,
+      # `POST /sessions/batch` and `POST /invoices/exports`.
+      #
+      # `publicKeyId` is nullable in the contract but always sent here: it names *which*
+      # published key did the wrapping, and without it a key rotation turns a decryptable
+      # payload into an undecryptable one with nothing to diagnose it by (§10.2).
+      #
+      # @param certificate [Certificate] from {PublicKeys#symmetric_key_encryption}
+      # @return [Hash]
+      def encryption_info(certificate)
+        {
+          encryptedSymmetricKey: Crypto.encode(certificate.encrypt(@key)),
+          initializationVector: Crypto.encode(@iv),
+          publicKeyId: certificate.public_key_id
+        }
+      end
+
+      # Redacted, and `#to_s` deliberately too: DESIGN.md §4.5 forbids leaking symmetric
+      # keys and IVs at default log level, and `"key: #{encryptor}"` in someone's debug
+      # line is exactly how that happens.
+      def to_s = REDACTED
+      def inspect = "#<Ksef::Crypto::Encryptor key=#{REDACTED} iv=#{REDACTED}>"
+
+      private
+
+      # A fresh cipher per call. `OpenSSL::Cipher` is stateful, so sharing one would make
+      # this class unsafe to use from two threads and would leave a half-consumed cipher
+      # behind after any exception.
+      def transform(direction, data)
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.public_send(direction)
+        # On by default; stated because PKCS#7 is a ledgered parameter (§10.1) and not
+        # something to leave to a library default.
+        cipher.padding = 1
+        cipher.key = @key
+        cipher.iv = @iv
+        cipher.update(data) + cipher.final
+      end
+
+      def check(name, value, expected)
+        bytes = value.to_s
+        unless bytes.bytesize == expected
+          raise CryptoError,
+                "The AES #{name} must be #{expected} bytes, got #{bytes.bytesize}. " \
+                "KSeF requires AES-256-CBC (docs/REFERENCE.md §10.1); a shorter key would " \
+                "silently select a weaker cipher."
+        end
+
+        # Frozen so a caller cannot mutate key material out from under a shared client.
+        bytes.dup.freeze
+      end
+    end
+  end
+end

data/lib/ksef/crypto/public_keys.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Crypto
+    # The Ministry's published encryption certificates, fetched and cached
+    # (docs/REFERENCE.md §10.2).
+    #
+    # `GET /security/public-key-certificates` is **unauthenticated** — the contract
+    # declares no `security` for it — so this needs no credential and can run before any
+    # authentication.
+    #
+    # ## Why there is a TTL, and why it is not "forever"
+    #
+    # Two rotation modes exist and must not be conflated. *Re-certification* issues a new
+    # certificate over the same key pair, leaving `publicKeyId` unchanged. *Key rotation*
+    # changes the key pair, so `publicKeyId` changes with it; a planned rotation publishes
+    # the successor early and both appear for one `usage` during the overlap, while an
+    # **emergency rotation revokes the old key and drops it from the list immediately**.
+    # Because the emergency case can happen at any moment, the list must not be cached
+    # indefinitely — and {#with_key_rotation} implements the documented recovery for the
+    # window between a rotation and the cache expiring.
+    #
+    # Thread-safe: one mutex guards the cache, and a `Ksef::Client` is required to be
+    # shareable across threads (DESIGN.md §5.2).
+    class PublicKeys
+      PATH = "security/public-key-certificates"
+
+      # An hour. Long enough that the list is fetched once per process in practice, short
+      # enough to bound how long a withdrawn key can linger. Callers who want none of it
+      # can pass `ttl: 0`.
+      DEFAULT_TTL = 3600
+
+      # `400` with this code means "the supplied key identifier is unknown or refers to a
+      # withdrawn key". The documented response is to re-fetch, re-select and repeat —
+      # see {#with_key_rotation}.
+      UNKNOWN_KEY_CODE = 21_470
+
+      # @param connection [Faraday::Connection] usually from {Ksef::HTTP::Connection.build}
+      # @param ttl [Numeric] seconds to cache the list for
+      # @param clock [#call] injected for tests; returns the current {Time}
+      def initialize(connection, ttl: DEFAULT_TTL, clock: -> { Time.now })
+        @connection = connection
+        @ttl = ttl
+        @clock = clock
+        @mutex = Mutex.new
+        @certificates = nil
+        @fetched_at = nil
+      end
+
+      # @return [Array<Certificate>] the cached list, fetching it if stale
+      def all
+        @mutex.synchronize { cached || load! }
+      end
+
+      # Discards the cache and fetches again. The recovery path of §10.2 after a key
+      # rotation, and the only way to see a newly published certificate before the TTL
+      # lapses.
+      #
+      # @return [Array<Certificate>]
+      def refresh!
+        @mutex.synchronize { load! }
+      end
+
+      # Applies the documented selection rule: filter by `usage`, require validity **at
+      # the moment of use**, and where several qualify prefer the latest `validFrom`.
+      #
+      # Not a judgement call — §10.2 states it, which matters because during a planned
+      # rotation overlap two certificates are legitimately valid for the same usage and
+      # picking the older one wastes the overlap the Ministry provided.
+      #
+      # @param kind [String] one of {Certificate::USAGES}
+      # @param at [Time, nil] the moment the key will be used; defaults to now
+      # @return [Certificate]
+      # @raise [Ksef::CryptoError] on an unknown usage, or when nothing published is valid
+      def for_usage(kind, at: nil)
+        validate_usage!(kind)
+        moment = at || now
+        usable = all.select { |certificate| certificate.usable_for?(kind) && certificate.valid_at?(moment) }
+        usable.max_by(&:valid_from) || raise(CryptoError, nothing_valid(kind, moment))
+      end
+
+      # The key that wraps the KSeF token during authentication (§4.5).
+      def token_encryption(at: nil) = for_usage(Certificate::KSEF_TOKEN_ENCRYPTION, at: at)
+
+      # The key that wraps a session's AES key (§10.1).
+      def symmetric_key_encryption(at: nil) = for_usage(Certificate::SYMMETRIC_KEY_ENCRYPTION, at: at)
+
+      # Runs an operation, and on the one error that says "your key is stale" re-fetches
+      # the list and runs it again.
+      #
+      # **This does not contradict the never-auto-retry-a-POST rule** (DESIGN.md §6.7). A
+      # `21470` is the API declining the request outright, so nothing happened server-side
+      # and there is no duplicate to create; and this is remediation — the second attempt
+      # carries a *different* key identifier — rather than a blind replay. §10.2 prescribes
+      # exactly this sequence.
+      #
+      # The block must therefore re-select the certificate itself, so pass the whole
+      # operation rather than a pre-built request:
+      #
+      #     keys.with_key_rotation do
+      #       session.open(encryption: encryptor.encryption_info(keys.symmetric_key_encryption))
+      #     end
+      #
+      # @return the block's value
+      def with_key_rotation
+        yield
+      rescue ApiError => e
+        raise unless e.code == UNKNOWN_KEY_CODE
+
+        refresh!
+        yield
+      end
+
+      private
+
+      def now = @clock.call
+
+      # A typo would otherwise read as "the Ministry publishes no such key", sending the
+      # reader to look for a rotation that never happened.
+      def validate_usage!(kind)
+        return if Certificate::USAGES.include?(kind)
+
+        raise CryptoError, "Unknown certificate usage #{kind.inspect}. " \
+                           "The contract declares #{Certificate::USAGES.map(&:inspect).join(" and ")}."
+      end
+
+      # Callers hold the mutex.
+      def cached = fresh? ? @certificates : nil
+
+      def fresh? = !@fetched_at.nil? && (now - @fetched_at) < @ttl
+
+      def load!
+        @certificates = Array(@connection.get(PATH).body).map { |payload| Certificate.from(payload) }.freeze
+        @fetched_at = now
+        @certificates
+      end
+
+      def nothing_valid(kind, moment)
+        published = @certificates.flat_map(&:usage).uniq
+        "No published KSeF certificate for usage #{kind.inspect} is valid at #{moment.iso8601}. " \
+          "The list carries #{@certificates.size} certificate(s) covering #{published.inspect}. " \
+          "If a rotation has just happened, PublicKeys#refresh! re-reads the list."
+      end
+    end
+  end
+end

data/lib/ksef/crypto.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "time"
+
+module Ksef
+  # Encryption of the payloads KSeF requires to be encrypted (docs/REFERENCE.md §10).
+  #
+  # Every parameter here is *ledgered*, not chosen. They come from
+  # `sesja-interaktywna.md` and `uwierzytelnianie.md` §2.2 — first-tier documentation —
+  # corroborated against both reference clients' cryptography services. Do not adjust one
+  # without re-reading §10 first; a mismatch here does not fail loudly, it produces a
+  # payload KSeF silently cannot decrypt.
+  #
+  # ## What lives where
+  #
+  # This module holds the primitives: the algorithm identifiers, base64, SHA-256 and the
+  # one RSA operation. {Crypto::Certificate} and {Crypto::PublicKeys} deal with the keys
+  # the Ministry publishes, {Crypto::Encryptor} with a session's symmetric key, and
+  # {Crypto::Digest} with the integrity metadata that travels beside every payload.
+  #
+  # Nothing here knows an API field name. Mapping to `EncryptionInfo` and
+  # `SendInvoiceRequest` is {Crypto::Encryptor}'s single concession to the wire format,
+  # and building the requests themselves belongs to the session layer.
+  module Crypto
+    # AES-256-CBC with PKCS#7 padding: 256-bit key, 128-bit IV, 128-bit block (§10.1).
+    # The Java client names the same thing `AES/CBC/PKCS5Padding`; for a 16-byte block
+    # PKCS#5 and PKCS#7 are identical, so that is not a divergence.
+    CIPHER = "aes-256-cbc"
+    KEY_BYTES = 32
+    IV_BYTES = 16
+    BLOCK_BYTES = 16
+
+    # RSAES-OAEP with SHA-256 **and** MGF1-SHA-256 (§10.1), used for both the symmetric
+    # key wrap and the KSeF-token payload of §4.5.
+    #
+    # All three options have to be stated. `OpenSSL::PKey::RSA#public_encrypt` cannot
+    # express an MGF1 digest at all, and OpenSSL's default MGF1 digest is SHA-1 — so
+    # setting `rsa_oaep_md` alone yields OAEP-SHA256-with-MGF1-SHA1, which is a *different
+    # scheme* that KSeF cannot unwrap. It fails at the far end, not here.
+    OAEP = { rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256" }.freeze
+
+    # Longest plaintext RSAES-OAEP can carry for a 2048-bit key: `k - 2*hLen - 2`, so
+    # `256 - 64 - 2`. Stated because it pins the digest — with SHA-1 the figure would be
+    # 214 — and because it is the reason both encrypted payloads here are small ones.
+    MAX_OAEP_PLAINTEXT_BYTES = 190
+
+    class << self
+      # Strict base64, no line breaks, for everything this gem *sends*.
+      def encode(bytes) = [bytes].pack("m0")
+
+      # Lenient base64 for everything it *receives*, which is the asymmetry that matters:
+      # `"m0"` raises on a line break, and how a server wraps a long value is its business.
+      # Nothing is silently accepted as a result — a certificate that decodes to garbage
+      # fails in `OpenSSL::X509::Certificate.new`, with a better message than we would give.
+      def decode(text) = text.to_s.unpack1("m")
+
+      # @return [String] the raw 32-byte digest; {Digest} is the base64-and-size form
+      def sha256(bytes) = OpenSSL::Digest::SHA256.digest(bytes)
+
+      # @param public_key [OpenSSL::PKey::RSA]
+      # @return [String] raw ciphertext, one RSA block wide
+      def rsa_encrypt(plaintext, public_key) = public_key.encrypt(plaintext, OAEP)
+    end
+  end
+end

data/lib/ksef/environments.rb

@@ -11,7 +11,7 @@ module Ksef
   # re-verifying it against that source and updating the ledger.
   #
   # Note the base URL already carries `/v2`; endpoint paths are appended bare. There is
-  # no `/api` segment (docs/REFERENCE.md §7.2).
+  # no `/api` segment (docs/REFERENCE.md §7 item 2).
   module Environments
     Environment = Data.define(:name, :base_url, :supports_test_data) do
       # TEST alone exposes the `/testdata/*` helper API and `/collective-identifiers*`.

data/lib/ksef/errors.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # The error hierarchy from DESIGN.md §6.7, extended with the 403 and 410 branches the
-# API actually returns (docs/REFERENCE.md §7.4).
+# API actually returns (docs/REFERENCE.md §7 item 4).
 #
 # This file defines many constants and no `Ksef::Errors`, so Zeitwerk cannot manage it —
 # `lib/ksef.rb` ignores it and requires it eagerly.
@@ -26,9 +26,42 @@ module Ksef
   # Challenge, KSeF-token, signature or JWT problems, including HTTP 401.
   class AuthenticationError < Error; end
 
-  # Raised locally by the FA(3) validator (DESIGN.md §7.7), never by the transport layer.
+  # Any locally-detected problem with the caller's input, before or instead of a request.
+  #
+  # The FA(3) validator (DESIGN.md §7.7) is the largest source, but **not the only one**, and
+  # an earlier version of this comment said "never by the transport layer" — which this gem
+  # then made false. It is also raised for a malformed KSeF number, a session or invoice
+  # reference that could alter a URL path, a challenge in the wrong format, a missing KSeF
+  # token, an unknown form code, and a malformed UPO download URL. Seventeen files raise it.
+  #
+  # So rescue it as "something I passed in is wrong", not as "my invoice is schema-invalid".
   class ValidationError < Error; end
 
+  # Downloaded bytes did not match the hash the server published for them
+  # (docs/REFERENCE.md §14.2).
+  #
+  # Its own class because the right response is specific and different from every other
+  # error here: **fetch it again**. Nothing is wrong with the request, the credentials or
+  # the document — the transfer was corrupted. It is not a {ValidationError}, which says
+  # the caller's own data is malformed, and it is not an {ApiError}, since the response was
+  # a success.
+  #
+  # It exists at all because the artifact this guards is a UPO: the legal proof that an
+  # invoice was received, fetched over an unauthenticated storage link. Silently archiving
+  # corrupt bytes as proof of receipt is the one outcome worth a dedicated error.
+  class IntegrityError < Error; end
+
+  # Encryption could not proceed: no published KSeF certificate is valid for the usage
+  # needed, or key material is the wrong size (docs/REFERENCE.md §10).
+  #
+  # Not in DESIGN.md §6.7's hierarchy, and added rather than folded into a neighbour
+  # because neither fits. It is not an {ApiError} — the request succeeded, the published
+  # list simply has nothing usable in it — nor a {ConfigurationError}, which is documented
+  # as local and pre-request. The one branch a caller may want to act on is "no valid key
+  # for this usage": after an emergency key rotation that is transient, and
+  # {Ksef::Crypto::PublicKeys#refresh!} is the remedy.
+  class CryptoError < Error; end
+
   # Any error response from the KSeF API.
   class ApiError < Error
     # @return [Integer, nil] HTTP status

data/lib/ksef/fa3/address.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ksef
+  module FA3
+    # A subject's address (`TAdres`).
+    #
+    # FA(3) does not model an address as structured fields, and neither does this. `TAdres`
+    # is `KodKraju` + `AdresL1` + optional `AdresL2` + optional `GLN`, where the two address
+    # lines are free text of up to 512 characters.
+    #
+    # **That shape is upstream's, not a simplification of it.** The only official code that
+    # reads an FA(3) address is `ksef-pdf-generator`'s `FA3/Adres.ts`, which models exactly
+    # those four elements; neither the C# nor the Java client models FA(3) at all, both
+    # taking the document as bytes. There is no upstream notion of a street or a postal code.
+    #
+    # So `street`, `city` and `postal_code` are **constructor conveniences, not state**: they
+    # compose into `line1` on the way in and are not retained. Retaining them would imply
+    # the document can express them, and would make an address built from parts unequal to
+    # the identical address given as a line — a distinction FA(3), KSeF and any reader of the
+    # invoice are all blind to, and one that would break DESIGN.md §7.6's round-trip law for
+    # the most ordinary use of the builder (docs/REFERENCE.md §8.2b).
+    #
+    # `GLN` is deliberately not carried: it is optional, nothing here needs it, and a parsed
+    # document that has one reports it through {Invoice#unmapped_elements} rather than
+    # losing it quietly.
+    Address = Data.define(:line1, :line2, :country) do
+      include Canonical
+
+      # @param line1 [String, nil] a formatted address line, for callers who have one
+      # @param line2 [String, nil] `AdresL2`, omitted from the document when nil
+      # @param country [String] `KodKraju`, ISO 3166-1 alpha-2
+      # @param street [String, nil] composed into `line1` together with the two below
+      # @param city [String, nil]
+      # @param postal_code [String, nil]
+      # @raise [Ksef::ValidationError] if there is no way to produce the mandatory `AdresL1`
+      def initialize(line1: nil, line2: nil, country: "PL", street: nil, city: nil, postal_code: nil)
+        composed = line1 || self.class.compose(street: street, city: city, postal_code: postal_code)
+        # `AdresL1` is mandatory in `TAdres`, so an address without one can never serialise.
+        # Refusing it at construction puts the error where the mistake is, rather than
+        # surfacing it later from `#to_fa3` on an invoice that looks complete.
+        raise ValidationError, "Address needs either line1, or street/city/postal_code" if composed.nil?
+
+        super(line1: Formatting.text(composed), line2: Formatting.text(line2),
+              country: Formatting.text(country))
+      end
+
+      def to_fa3
+        content = { "KodKraju" => country, "AdresL1" => line1 }
+        content["AdresL2"] = line2 unless line2.nil?
+        content
+      end
+
+      # `"Prosta 1, 00-001 Warszawa"` — street, then postal code and city, skipping whatever
+      # is absent so a partial address still yields something usable.
+      #
+      # @return [String, nil] nil when there is nothing to compose from
+      def self.compose(street:, city:, postal_code:)
+        locality = [postal_code, city].compact.join(" ").strip
+        parts = [street, locality].reject { |part| part.nil? || part.empty? }
+        parts.empty? ? nil : parts.join(", ")
+      end
+    end
+  end
+end

data/lib/ksef/fa3/advance_checks.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ksef
+  module FA3
+    # Tier 1a's checks on {Order} and {AdvanceInvoice} — the two structures that make an
+    # invoice part of an advance-payment sequence (docs/REFERENCE.md §8.5).
+    #
+    # Mixed into {ModelValidator}. `Zamowienie`'s positions are checked the way `FaWiersz`'s
+    # are, against the same generated enum and the same `xsd:token` facets, because they are
+    # the same kind of thing said about the order rather than about the sale.
+    module AdvanceChecks
+      # Included rather than assumed present: constant lookup is lexical.
+      include FieldChecks
+
+      private
+
+      def advance_errors(invoice)
+        [*order_errors(invoice.order), *settled_errors(invoice.advances)]
+      end
+
+      def order_errors(order)
+        return [] if order.nil?
+        return [Issue.new(field: "order", message: "is not a Ksef::FA3::Order")] unless order.is_a?(Order)
+
+        order.lines.each_with_index.flat_map { |line, index| order_line_errors(line, index) }
+      end
+
+      def order_line_errors(line, index)
+        field = "order.lines[#{index}]"
+        return [Issue.new(field: field, message: "is not a Ksef::FA3::OrderLine")] unless line.is_a?(OrderLine)
+
+        [
+          *text_errors(line.name, "#{field}.name", LONG_TEXT),
+          *text_errors(line.unit, "#{field}.unit", SHORT_TEXT),
+          # `P_12Z` is optional, unlike `FaWiersz`'s `P_12` — an order position need not state
+          # a rate — so nil is a value here rather than a missing one.
+          line.vat_rate.nil? ? nil : enum_issue("#{field}.vat_rate", "TStawkaPodatku", line.vat_rate)
+        ].compact
+      end
+
+      def settled_errors(advances)
+        advances.each_with_index.flat_map do |advance, index|
+          field = "advances[#{index}]"
+          next [Issue.new(field: field, message: "is not a Ksef::FA3::AdvanceInvoice")] unless
+            advance.is_a?(AdvanceInvoice)
+
+          # The KSeF number's *format* is tier 2's, for the reason §8.4b gives: the only
+          # pattern this gem holds comes from the OpenAPI contract, and the XSD's is wider.
+          [*text_errors(advance.number, "#{field}.number", SHORT_TEXT),
+           encoding_issue(advance.ksef_number, "#{field}.ksef_number")].compact
+        end
+      end
+    end
+  end
+end

data/lib/ksef/fa3/advance_invoice.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ksef
+  module FA3
+    # An advance invoice a settlement invoice settles (`FakturaZaliczkowa`).
+    #
+    # A `ROZ` — the invoice of art. 106f ust. 3, issued once the goods are delivered — names
+    # every advance invoice already issued for the same transaction, up to **100** of them.
+    #
+    # ## The choice is inverted from {CorrectedInvoice}'s, and that is the schema's doing
+    #
+    # `DaneFaKorygowanej` pairs its *marker* with the KSeF number. `FakturaZaliczkowa` pairs it
+    # with the plain one:
+    #
+    # - in KSeF → `NrKSeFFaZaliczkowej` alone, *"numer identyfikujący fakturę zaliczkową w
+    #   KSeF"*;
+    # - outside KSeF → `NrKSeFZN`, *"znacznik faktury zaliczkowej wystawionej poza KSeF"*,
+    #   followed by `NrFaZaliczkowej`, the number it carried on paper.
+    #
+    # So the two branches name *different fields*, and modelling it as one nil-able value would
+    # lose which. Both are carried, and exactly one must be given — checked here, so a document
+    # naming both or neither cannot be built.
+    AdvanceInvoice = Data.define(:ksef_number, :number)
+
+    # Reopened rather than using a `Data.define` block, so the constant below lands on the
+    # class *and* resolves from inside `#initialize` — a block body's constant lookup is
+    # lexical, against `Ksef::FA3`, so `ONE_OF` defined on the class would not be found there.
+    class AdvanceInvoice
+      # `#with` must re-run the constructor; on Ruby 3.2 it otherwise skips every invariant.
+      include Canonical
+
+      ONE_OF = "An advance invoice is named by exactly one of ksef_number: (its KSeF number) " \
+               "or number: (its own number, for one issued outside KSeF). The schema puts a " \
+               "choice here, so naming both or neither is not a document that exists."
+
+      # @param ksef_number [String, nil] `NrKSeFFaZaliczkowej`, for an advance invoice issued
+      #   through KSeF
+      # @param number [String, nil] `NrFaZaliczkowej`, for one issued outside it
+      # @raise [Ksef::ValidationError] unless exactly one of the two is given
+      def initialize(ksef_number: nil, number: nil)
+        given = [ksef_number, number].compact
+        raise ValidationError, ONE_OF unless given.size == 1
+
+        super(ksef_number: Formatting.text(ksef_number), number: Formatting.text(number))
+      end
+
+      def to_fa3
+        return { "NrKSeFFaZaliczkowej" => ksef_number } if ksef_number
+
+        # `TWybor1` has one member: the marker is present or absent, with no "no" to write.
+        { "NrKSeFZN" => "1", "NrFaZaliczkowej" => number }
+      end
+    end
+  end
+end

data/lib/ksef/fa3/advance_reader.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Ksef
+  module FA3
+    # Reads the two elements that make an invoice part of an advance-payment sequence:
+    # `Zamowienie`, the order a `ZAL` collects against, and `FakturaZaliczkowa`, the advance
+    # invoices a `ROZ` settles (docs/REFERENCE.md §8.5).
+    #
+    # Split out for the reason {CorrectionReader} is: it is the part of reading an invoice that
+    # is entirely about one family of types.
+    module AdvanceReader
+      class << self
+        # Namespace-aware element reading; see {NodeReader}.
+        include NodeReader
+
+        # @return [Order, nil]
+        def order_from(fa_node)
+          node = element(fa_node, "Zamowienie")
+          return nil if node.nil?
+
+          Order.new(total: text!(node, "WartoscZamowienia"),
+                    lines: elements(node, "ZamowienieWiersz").map { |row| order_line_from(row) })
+        end
+
+        # @return [Array<AdvanceInvoice>] empty when the invoice settles nothing
+        def advances_from(fa_node)
+          elements(fa_node, "FakturaZaliczkowa").map { |node| advance_from(node) }
+        end
+
+        private
+
+        def order_line_from(row)
+          OrderLine.new(
+            name: text(row, "P_7Z"), unit: text(row, "P_8AZ"), quantity: text(row, "P_8BZ"),
+            net_unit_price: text(row, "P_9AZ"), net_amount: text(row, "P_11NettoZ"),
+            vat_amount: text(row, "P_11VatZ"), vat_rate: text(row, "P_12Z"),
+            row_number: text(row, "NrWierszaZam"), state_before: text(row, "StanPrzedZ")
+          )
+        end
+
+        # The schema's choice, read the way {CorrectionReader.reference_from} reads its own:
+        # a document stating neither branch is refused rather than being repaired into one,
+        # since choosing for it would assert something nobody wrote.
+        def advance_from(node)
+          ksef_number = text(node, "NrKSeFFaZaliczkowej")
+          return AdvanceInvoice.new(ksef_number: ksef_number) if ksef_number
+
+          number = text(node, "NrFaZaliczkowej")
+          return AdvanceInvoice.new(number: number) if number
+
+          raise ValidationError,
+                "FakturaZaliczkowa states neither NrKSeFFaZaliczkowej nor NrFaZaliczkowej. " \
+                "The schema requires one of the two, and picking one would assert where the " \
+                "advance invoice was issued."
+        end
+      end
+    end
+  end
+end