ksef_client 0.1.0.rc1 → 0.1.0

data/lib/ksef/auth/validator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ksef
+  module Auth
+    # XSD validation for `AuthTokenRequest`, mirroring {Ksef::FA3::Validator}.
+    #
+    # Both pinned schema files are structurally identical — diffing them shows the only
+    # differences are the target namespace and the three IP patterns, which v2.0 got wrong
+    # badly enough that libxml2 will not compile the file at all (docs/REFERENCE.md §14.4).
+    #
+    # So **v2.1's file is the single source of validation rules**, and its target namespace
+    # is rewritten in memory to match the document being checked. Exactly the approach
+    # {Ksef::FA3::Validator} takes to its remote `schemaLocation`, and for the same reason:
+    # the pinned files stay byte-identical, so their recorded digests keep verifying.
+    #
+    # The upshot is that a 2.0 document — which is what the API expects and what both
+    # official clients emit — gets validated against rules that actually compile, which is
+    # strictly better than validating it against v2.0 itself. That is impossible.
+    module Validator
+      SCHEMA_DIR = File.expand_path("schema", __dir__)
+      SOURCE = File.join(SCHEMA_DIR, "schemat_auth_v2-1.xsd")
+      SOURCE_NAMESPACE = NAMESPACES.fetch("2.1")
+
+      class << self
+        # @param namespace [String] one of {Ksef::Auth::NAMESPACES}' values
+        # @return [Nokogiri::XML::Schema] memoised per namespace; compiling is not free and
+        #   a client authenticating repeatedly should pay once
+        def schema_for(namespace)
+          reject_unknown_namespace(namespace)
+          schemas[namespace] ||= Nokogiri::XML::Schema(retargeted_source(namespace))
+        end
+
+        # @param xml [String, Nokogiri::XML::Document]
+        # @return [Array<String>] validation messages, empty when the document is valid
+        def errors_for(xml)
+          document = xml.is_a?(Nokogiri::XML::Document) ? xml : Nokogiri::XML(xml)
+          schema_for(namespace_of(document)).validate(document).map(&:message)
+        end
+
+        # @return [Boolean]
+        def valid?(xml) = errors_for(xml).empty?
+
+        # @param advisory [String] appended to the message; used to explain that a failure
+        #   may stem from an upstream schema defect rather than the caller's data
+        # @raise [Ksef::ValidationError] listing every schema violation
+        def validate!(xml, advisory: "")
+          errors = errors_for(xml)
+          return true if errors.empty?
+
+          detail = errors.map { |e| "  - #{e}" }.join("\n")
+          raise ValidationError, "AuthTokenRequest is not schema-valid:\n#{detail}#{advisory}"
+        end
+
+        private
+
+        def schemas = @schemas ||= {}
+
+        # Read from the document rather than assumed, so a request built for either version
+        # validates against the matching rules — but only the two known namespaces are
+        # accepted, otherwise a typo would silently validate against itself.
+        def namespace_of(document)
+          document.root&.namespace&.href
+        end
+
+        def reject_unknown_namespace(namespace)
+          return if NAMESPACES.value?(namespace)
+
+          raise ValidationError,
+                "AuthTokenRequest declares namespace #{namespace.inspect}, which is not a known " \
+                "schema version. Expected one of #{NAMESPACES.values.map(&:inspect).join(", ")}."
+        end
+
+        def retargeted_source(namespace)
+          source = File.read(SOURCE, encoding: "UTF-8")
+          return source if namespace == SOURCE_NAMESPACE
+
+          source.gsub(SOURCE_NAMESPACE, namespace)
+        end
+      end
+    end
+  end
+end

data/lib/ksef/auth/xades.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ksef
+  module Auth
+    # The namespace URIs and algorithm identifiers of the XAdES signature
+    # (docs/REFERENCE.md §4.3).
+    #
+    # Its own module so that {Signer} and {SignatureTemplate} share one definition rather
+    # than one referring to the other's constants. Included rather than referenced, so
+    # `Signer::DS` keeps resolving — these names are part of the public vocabulary and are
+    # asserted directly in the specs.
+    module Xades
+      # Read from pinned artifacts, not from memory: `spec/fixtures/xades/` holds the
+      # schemas upstream redistributes, and these are their target namespaces (§4.3).
+      DS = "http://www.w3.org/2000/09/xmldsig#"
+      XADES = "http://uri.etsi.org/01903/v1.3.2#"
+
+      # Every one of these appears in the Ministry's allow-list in `auth/podpis-xades.md`,
+      # so the combination needs no further verification (§4.3).
+      CANONICALIZATION = "http://www.w3.org/2001/10/xml-exc-c14n#"
+      SIGNATURE_METHOD = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+      DIGEST_METHOD = "http://www.w3.org/2001/04/xmlenc#sha256"
+      ENVELOPED_SIGNATURE = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
+
+      # The one identifier the allow-list does not state. Fixed by ETSI TS 101 903 and
+      # taken from `ksef-client-csharp`'s `SignatureService.SignedPropertiesType`; ledgered
+      # in §4.3 with that provenance rather than treated as common knowledge.
+      SIGNED_PROPERTIES_TYPE = "http://uri.etsi.org/01903#SignedProperties"
+
+      C14N_MODE = Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0
+
+      SIGNATURE_ID = "Signature"
+      SIGNED_PROPERTIES_ID = "SignedProperties"
+
+      XPATH_NAMESPACES = { "ds" => DS, "xades" => XADES }.freeze
+    end
+  end
+end

data/lib/ksef/auth.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ksef
+  # Authentication against KSeF (docs/REFERENCE.md §4).
+  module Auth
+    # Both schema versions of the `AuthTokenRequest` document.
+    #
+    # **2.0 is the default, and that is a deliberate correction.** v2.1 is the newer file,
+    # but every piece of available evidence points at 2.0 as what the API actually expects:
+    # both official clients bind to it (`[XmlRoot(Namespace = "…/2.0")]` in
+    # `AuthenticationTokenRequest.cs`; JAXB classes generated against 2.0 in
+    # `ksef-client-java`), the Java client bundles its own copy of the 2.0 schema, and
+    # every worked example in `CIRFMF/ksef-api` declares 2.0. Nothing observed so far
+    # emits 2.1. See §14.4.
+    NAMESPACES = {
+      "2.0" => "http://ksef.mf.gov.pl/auth/token/2.0",
+      "2.1" => "http://ksef.mf.gov.pl/auth/token/2.1"
+    }.freeze
+
+    DEFAULT_SCHEMA_VERSION = "2.0"
+
+    class << self
+      # Parses the contract's `date-time` fields.
+      #
+      # Returns `nil` rather than raising on an unparseable value: these timestamps are
+      # informational — expiry hints, start times — and a malformed one is no reason to
+      # fail an authentication that otherwise succeeded. The fields that actually matter
+      # are the tokens themselves.
+      #
+      # @return [Time, nil]
+      def time(value)
+        return value if value.is_a?(Time)
+        return nil if value.nil? || value.to_s.empty?
+
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/ksef/client/receipt.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ksef
+  class Client
+    # What {Ksef::Client#send_invoice} returns: proof that KSeF accepted the *upload*, and
+    # the pair of references needed to find out what became of the invoice.
+    #
+    # ## Why `#reference` returns the whole object
+    #
+    # DESIGN.md §8's contract reads `client.wait_until_accepted(result.reference)`, which
+    # looks like it wants a single string. It cannot be one: every status and UPO endpoint is
+    # keyed on **both** the session and the invoice (`GET /sessions/{ref}/invoices/{ref}`), so
+    # an invoice reference on its own cannot look anything up.
+    #
+    # Rather than bend the API into passing two arguments, or hiding the session on a client
+    # that has to stay thread-safe, `#reference` returns `self` — because the pair genuinely
+    # *is* the reference of a submission. §8's snippet then runs verbatim, and nothing has to
+    # remember which session an invoice went through.
+    #
+    # Note what this is **not**: acceptance. `POST .../invoices` answers `202`, meaning the
+    # upload was taken, and whether the invoice itself is accepted arrives asynchronously
+    # (§12.1). {Ksef::Client#wait_until_accepted} is what settles that.
+    Receipt = Data.define(:session_reference, :invoice_reference, :session_valid_until) do
+      # See the class note: the pair is the reference.
+      def reference = self
+
+      # The invoice's own reference number, which is what a human quotes.
+      def to_s = invoice_reference.to_s
+
+      # The session closes itself at this point (§11), after which the collective UPO is
+      # generated. Exposed because a long batch may want to check rather than assume.
+      def session_expired?(now = Time.now)
+        !session_valid_until.nil? && session_valid_until <= now
+      end
+    end
+  end
+end

data/lib/ksef/client/session.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ksef
+  class Client
+    # The handle {Ksef::Client#session} yields — one open session, for sending several
+    # invoices through deliberately.
+    #
+    # ## Why batching is opt-in rather than the default
+    #
+    # `Ksef::Client#send_invoice` opens a fresh session per call (docs/REFERENCE.md §11.2a,
+    # decided 2026-08-23). That is the safe default, not the efficient one: a session lives
+    # twelve hours and takes ten thousand invoices, so opening one per invoice spends
+    # `POST /sessions/online`'s budget of 30/min where a batch would spend one.
+    #
+    # So this exists for anyone sending more than a handful — and it is a block, not a
+    # returned object, because the session must be closed. Closing is what triggers
+    # generation of the collective UPO (§11); a session merely abandoned closes itself at
+    # `validUntil` up to twelve hours later, and the proof of receipt waits that long with it.
+    #
+    #     client.session do |batch|
+    #       invoices.each { |invoice| batch.send_invoice(invoice) }
+    #     end   # ← closed here, whatever happened inside
+    #
+    # The whole session shares one symmetric key, which is exactly why {Sessions::Online}
+    # binds the encryptor to the session rather than taking one per send.
+    class Session
+      # @return [Ksef::Sessions::Online::Session] the open session, key and all
+      attr_reader :opened
+
+      def initialize(client, opened)
+        @client = client
+        @opened = opened
+        @receipts = []
+      end
+
+      # Validates, encrypts and submits one invoice into this session.
+      #
+      # @param invoice [#to_xml, String]
+      # @param validate [Boolean] run the FA(3) validator first. On by default: a document
+      #   KSeF will reject costs a round trip and a slot in the session, and the local
+      #   validator is free (DESIGN.md §7.7).
+      # @return [Receipt]
+      def send_invoice(invoice, validate: true)
+        @client.validate_invoice!(invoice) if validate
+        submission = @client.sessions.send_invoice(@opened, invoice)
+
+        Receipt.new(
+          session_reference: @opened.reference_number,
+          invoice_reference: submission.reference_number,
+          session_valid_until: @opened.valid_until
+        ).tap { |receipt| @receipts << receipt }
+      end
+
+      # Every receipt from this session, in the order they were submitted.
+      #
+      # Worth keeping: after {Ksef::Client#session} returns, the collective UPO covers
+      # exactly these invoices, and a caller that discarded the receipts has no way to ask
+      # about any of them individually.
+      #
+      # @return [Array<Receipt>]
+      def receipts = @receipts.dup
+
+      def reference_number = @opened.reference_number
+
+      def to_s = reference_number.to_s
+    end
+  end
+end

data/lib/ksef/client.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module Ksef
+  # The facade — DESIGN.md §8's public API contract.
+  #
+  #     client = Ksef::Client.new(
+  #       env:  :test,
+  #       auth: Ksef::Auth::Token.new(context_nip: "9999999999", token: ENV["KSEF_TOKEN"])
+  #     )
+  #
+  #     result = client.send_invoice(invoice)
+  #     status = client.wait_until_accepted(result.reference)
+  #     status.ksef_number
+  #     upo    = client.upo(result.reference)
+  #
+  # Everything below the facade is usable directly — {Sessions::Online}, {Sessions::Status},
+  # {UPO::Client} and {Auth::Client} are all public, and a caller who wants the granular
+  # calls should reach for them. This assembles them into the twenty-line path.
+  #
+  # ## Authentication happens once, lazily, and under a mutex
+  #
+  # Constructing a client performs no I/O. The first call that needs a credential runs the
+  # whole KSeF-token flow — challenge, encrypt, submit, poll, redeem — and hands the result
+  # to {Auth::AccessToken}, which then refreshes itself at ~80% of its lifetime. A burst of
+  # threads produces one authentication, not one each, because the check happens inside the
+  # lock.
+  #
+  # ## Thread safety
+  #
+  # A single instance is safe to share (DESIGN.md §5.2), and the design is what makes that
+  # true rather than a promise about it. The configuration is frozen at construction; the
+  # Faraday connections are shared and stateless; the only mutable state is the memoised
+  # credential, guarded by one mutex. **No session is ever held on the client** — that was
+  # the deciding argument for opening a fresh one per {#send_invoice} (§11.2a), since a
+  # session cached here would be mutable state two threads could submit into at once.
+  class Client
+    # @param env [Symbol, Ksef::Environments::Environment] `:test`, `:demo` or `:prod`
+    # @param auth [Ksef::Auth::Token, Ksef::Auth::AccessToken] a KSeF-token credential to
+    #   authenticate with, or an already-redeemed access token
+    # @param options [Hash] passed to {Ksef::Configuration} — `logger:`, `timeout:`,
+    #   `adapter:`, `proxy:`, `retry_policy:`
+    # @param clock [#call] returns the current {Time}; the same injection {Sessions::Status}
+    #   and {Crypto::PublicKeys} already take. It reaches {Crypto::PublicKeys}, which decides
+    #   whether a published certificate is currently valid, and the {Auth::AccessToken} this
+    #   client builds, which decides staleness against the `validUntil` KSeF returned.
+    #
+    #   **It does not reach an `Auth::AccessToken` passed in as `auth:`** — that one is already
+    #   constructed and carries whatever clock it was built with. Build it with the same clock
+    #   if you need both pinned.
+    #
+    #   **This is what makes a recorded cassette replayable.** A recorded access token is
+    #   valid for fifteen minutes and {Auth::AccessToken} refreshes at 80% of that, so about
+    #   twelve minutes after recording a replay against the real clock reads it as stale and
+    #   issues a `POST /auth/token/refresh` that the cassette has no interaction for. Pinning
+    #   the clock to the moment of recording replays the flow as it happened, rather than
+    #   rewriting what KSeF said (`spec/recorded/session_flow_spec.rb`).
+    # @param sleeper [#call] receives a number of seconds; used between polls of the
+    #   authentication operation, which is asynchronous ({Auth::Client#wait_until_complete}).
+    #   {Sessions::Status#poll} has taken one since it was written and {#wait_until_accepted}
+    #   exposes it; this is the same seam for the one poll the facade performs on its own.
+    #   A replay wants a no-op — the recorded tier spent eight of its nine seconds asleep
+    #   between status calls whose answers were already on disk.
+    def initialize(env: :test, auth: nil, clock: -> { Time.now }, sleeper: method(:sleep), **)
+      @config = Configuration.new(env: env, auth: auth, **)
+      @mutex = Mutex.new
+      @clock = clock
+      @sleeper = sleeper
+      @credential = auth.is_a?(Auth::AccessToken) ? auth : nil
+    end
+
+    # @return [Ksef::Configuration] frozen
+    attr_reader :config
+
+    # Sends one invoice, in a session of its own.
+    #
+    # Fresh session per call is the decided default (§11.2a). For more than a handful of
+    # invoices use {#session}, which opens one session for all of them. The budgets to compare
+    # are the hourly ones: 120 session opens an hour against 180 invoice sends (§6.1). Per
+    # minute both are 30, so the saving is real but smaller than it first looks.
+    #
+    # @param invoice [#to_xml, String] an FA(3) document
+    # @param validate [Boolean] run the FA(3) validator first
+    # @return [Receipt]
+    # @param encryptor [Crypto::Encryptor, nil] see {#session}; for the recorded tier only
+    def send_invoice(invoice, validate: true, encryptor: nil)
+      session(encryptor: encryptor) { |batch| batch.send_invoice(invoice, validate: validate) }
+    end
+
+    # Opens one session, yields a handle, and closes it however the block ends.
+    #
+    # Closing is what starts generation of the collective UPO (§11), so it matters that it
+    # happens — hence a block rather than a returned session.
+    #
+    # @yieldparam batch [Session]
+    # @param encryptor [Crypto::Encryptor, nil] the session's symmetric key. Generated fresh
+    #   when omitted, which is what every caller should do — a key is per-session by design
+    #   (docs/REFERENCE.md §11.2a) and reusing one across sessions is a step towards reusing
+    #   it across *documents*, which is what the per-session binding exists to prevent.
+    #
+    #   It is injectable for exactly one reason: **the recorded test tier** (DESIGN.md §9.1).
+    #   `Encryptor.generate` draws a random key and IV, and RSA-OAEP padding is randomised on
+    #   top, so a recorded request body can never be reproduced — a replayed run has to supply
+    #   the key the recording used. Without this seam the recorded tier would have to drive
+    #   {Sessions::Online} directly and would stop testing the facade a user actually calls.
+    # @return the block's value
+    def session(form_code: Sessions::DEFAULT_FORM_CODE, upo_version: Sessions::UPO_VERSION,
+                encryptor: nil)
+      # Wrapped in the §10.2 remediation: certificates are cached for an hour, so an
+      # emergency key rotation inside that window makes the cached `publicKeyId` unknown and
+      # the open fails with `21470`. `with_key_rotation` re-fetches and re-selects, and the
+      # certificate is chosen *inside* the block so the second attempt uses the new key.
+      #
+      # This is not a retry of a POST in the sense the hard rule forbids: a 21470 means the
+      # request was declined outright, so there is no session to duplicate.
+      opened = public_keys.with_key_rotation do
+        sessions.open(
+          encryptor: encryptor || Crypto::Encryptor.generate,
+          certificate: public_keys.symmetric_key_encryption,
+          form_code: form_code,
+          upo_version: upo_version
+        )
+      end
+      yield Session.new(self, opened)
+    ensure
+      sessions.close(opened) if opened
+    end
+
+    # Waits until KSeF has decided about one invoice.
+    #
+    # @param receipt [Receipt] from {#send_invoice}
+    # @return [Ksef::Sessions::InvoiceState] always accepted
+    # @raise [Ksef::InvoiceRejectedError] with KSeF's own wording, and the original's
+    #   references when the rejection was a duplicate
+    # @raise [Ksef::TimeoutError] when the deadline passes with the invoice still processing
+    def wait_until_accepted(receipt, **)
+      status_client.wait_until_accepted(receipt.session_reference, receipt.invoice_reference, **)
+    end
+
+    # The current status of one invoice, without waiting.
+    #
+    # @return [Ksef::Sessions::InvoiceState]
+    def invoice_status(receipt)
+      status_client.invoice(receipt.session_reference, receipt.invoice_reference)
+    end
+
+    # The UPO for one invoice — the signed proof of receipt. **Archive the bytes verbatim**
+    # (§12); {UPO::Document#write} does that.
+    #
+    # Uses the metered per-invoice route rather than chasing the unmetered pre-signed link,
+    # which is the opposite of what §14.2 prefers — deliberately, and only here. Obtaining
+    # that link costs a metered status call first, so for a single invoice the direct route
+    # is one request against two. The unmetered link earns its keep on *collective* UPOs and
+    # in bulk, where {UPO::Client#fetch} is the right entry point.
+    #
+    # @param receipt [Receipt]
+    # @return [Ksef::UPO::Document]
+    def upo(receipt)
+      upo_client.for_invoice(receipt.session_reference, receipt.invoice_reference)
+    end
+
+    # The collective UPO for a whole session, following the unmetered link when it is still
+    # valid. Available only after the session has closed *and* finished processing, so call
+    # {#wait_for_session} first — `170` means closed but not done.
+    #
+    # @param session_reference [String]
+    # @return [Array<Ksef::UPO::Document>] one per page; a collective UPO holds at most
+    #   10 000 invoices, and reading only the first page loses proof for the rest (§12)
+    def collective_upo(session_reference)
+      status_client.session(session_reference).upo_pages.map do |page|
+        upo_client.fetch(page, session_reference: session_reference)
+      end
+    end
+
+    # @return [Ksef::Sessions::SessionState]
+    def session_status(session_reference) = status_client.session(session_reference)
+
+    # Waits until KSeF has finished processing a whole session.
+    #
+    # **Closing a session and finishing it are two different clocks.** {#session} closes on
+    # the way out, which *starts* asynchronous generation of the collective UPO; the session
+    # then sits at `170` until that finishes at `200`. {#wait_until_accepted} does not cover
+    # it — an accepted invoice says nothing about the session's own progress — so a caller
+    # that sends, waits for the invoice and then asks for {#collective_upo} is racing.
+    #
+    # This existed on {Sessions::Status} from the start and was simply not reachable through
+    # the facade, which left `#collective_upo`'s own documentation telling callers to poll
+    # {#session_status} by hand. Two places in this repository did exactly that, and one of
+    # them got it wrong: `spec/integration/session_flow_spec.rb` read the status once and
+    # asserted a terminal code, which passed until the nightly of 2026-09-13 found TEST still
+    # at `170`.
+    #
+    # @param session_reference [String]
+    # @param deadline [Numeric] seconds; defaults to {Sessions::Status::DEFAULT_DEADLINE}
+    # @yieldparam state [Ksef::Sessions::SessionState] after each poll, for progress reporting
+    # @return [Ksef::Sessions::SessionState] no longer in progress
+    # @raise [Ksef::TimeoutError] when the deadline passes with the session still working
+    def wait_for_session(session_reference, **, &)
+      status_client.wait_for_session(session_reference, **, &)
+    end
+
+    # Downloads an invoice KSeF holds, by its KSeF number.
+    #
+    # @param ksef_number [String, Ksef::KsefNumber]
+    # @return [String] FA(3) XML, verbatim
+    def download_invoice(ksef_number) = invoices.download(ksef_number)
+
+    # Runs the FA(3) validator, if the document knows how to validate itself.
+    #
+    # A raw XML String does not — the transport layer accepts any `#to_xml` or a String
+    # (DESIGN.md §5), and refusing one here would break that contract to enforce a check the
+    # caller may already have done. But it is still **bytes**, and the byte-level admission
+    # rules of docs/REFERENCE.md §15.1 apply to bytes whatever produced them. So a String gets
+    # tier 1b: a review on 2026-08-24 pointed out that the gem, handed the poison fixture as a
+    # String, would have shipped the very document tier 1 was built to stop — mis-encoded ERP
+    # text being precisely the case §15.1 calls likely.
+    #
+    # Not the schema tier: validating a caller's own XML against FA(3) would reject the batch
+    # and RR structures the transport layer is meant to carry.
+    #
+    # @raise [Ksef::ValidationError]
+    def validate_invoice!(invoice)
+      return invoice.validate! if invoice.respond_to?(:validate!)
+      return unless invoice.is_a?(String)
+
+      issues = FA3::DocumentValidator.errors_for(invoice)
+      return if issues.empty?
+
+      raise ValidationError,
+            "The XML given is not admissible:\n#{issues.sort.map { |issue| "  - #{issue}" }.join("\n")}"
+    end
+
+    # @return [Ksef::Sessions::Online]
+    def sessions = @sessions ||= Sessions::Online.new(connection, credential)
+
+    # @return [Ksef::Sessions::Status]
+    #
+    # Named `status_client` rather than `status` so it cannot be mistaken for
+    # {#invoice_status} or {#session_status}, which return an actual status.
+    def status_client = @status_client ||= Sessions::Status.new(connection, credential)
+
+    # @return [Ksef::UPO::Client]
+    def upo_client
+      @upo_client ||= UPO::Client.new(
+        connection, credential, clock: @clock, storage: HTTP::Connection.storage(config)
+      )
+    end
+
+    # @return [Ksef::Invoices::Client]
+    def invoices = @invoices ||= Invoices::Client.new(connection, credential)
+
+    # The clock goes here too, and that is not symmetry for its own sake: `#for_usage` filters
+    # published certificates on `valid_at?`, so a replay running after they expire finds none
+    # and raises. The cassettes' certificates run to 2027-09-29 — pinning only
+    # {Auth::AccessToken} would have left the tier a time bomb with a longer fuse.
+    #
+    # @return [Ksef::Crypto::PublicKeys]
+    def public_keys = @public_keys ||= Crypto::PublicKeys.new(connection, clock: @clock)
+
+    # @return [Ksef::Auth::Client]
+    def auth = @auth ||= Auth::Client.new(connection)
+
+    # The access token, authenticating first if that has not happened yet.
+    #
+    # @return [Ksef::Auth::AccessToken]
+    def credential
+      @mutex.synchronize { @credential ||= authenticate_with_rotation! }
+    end
+
+    def inspect = "#<Ksef::Client env=#{config.environment.name.inspect}>"
+
+    private
+
+    def connection = @connection ||= HTTP::Connection.build(config)
+
+    # The KSeF-token flow of §4.5, end to end: submit, poll, redeem. Callers hold the mutex.
+    def authenticate!
+      initiated = auth.submit_ksef_token(token_request)
+      auth.authenticate!(initiated.reference_number, token: initiated.authentication_token,
+                                                     sleeper: @sleeper)
+
+      Auth::AccessToken.new(
+        auth.redeem(token: initiated.authentication_token), client: auth, clock: @clock
+      )
+    end
+
+    # A fresh challenge and the key that wraps the token. Both are fetched here rather than
+    # cached: the challenge is single-use and lives ten minutes (§4), and the certificate
+    # comes from {Crypto::PublicKeys}, which does its own caching.
+    def token_request
+      credential_token.authentication_request(
+        challenge: auth.challenge, certificate: public_keys.token_encryption
+      )
+    end
+
+    # Authentication consumes a published key too, so it gets the same remediation. The
+    # challenge is re-fetched on the second attempt as well, which is correct: challenges are
+    # single-use, so replaying one would fail for a different reason.
+    def authenticate_with_rotation!
+      public_keys.with_key_rotation { authenticate! }
+    end
+
+    # A usable credential, or a message saying where one comes from — the failure a caller
+    # is most likely to hit on their first attempt.
+    def credential_token
+      token = config.auth
+      return token if token.respond_to?(:authentication_request)
+
+      raise ConfigurationError,
+            "Ksef::Client needs auth: a Ksef::Auth::Token (or an already-redeemed " \
+            "Ksef::Auth::AccessToken), got #{token.inspect}. A KSeF token is minted by " \
+            "POST /tokens after a one-time XAdES authentication (docs/REFERENCE.md §6a.2)."
+    end
+  end
+end

data/lib/ksef/crypto/certificate.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Crypto
+    # One entry from `GET /security/public-key-certificates` — the contract's
+    # `PublicKeyCertificate` (docs/REFERENCE.md §10.2).
+    #
+    # The Ministry publishes a list rather than a single key, and the entries are not
+    # interchangeable: `usage` says what each may encrypt, and two entries can be valid at
+    # once during a planned key rotation. {PublicKeys} applies the documented selection
+    # rule; this class is the value object it selects from.
+    Certificate = Data.define(:certificate, :certificate_id, :public_key_id, :valid_from, :valid_to, :usage)
+
+    # Reopened rather than using a `Data.define` block so the usage constants land on the
+    # class rather than on `Object`.
+    class Certificate
+      # The two members of the contract's `PublicKeyCertificateUsage` enum. Keeping them
+      # here rather than as bare strings at call sites means a typo is a `NameError` at
+      # load time instead of an empty selection at runtime.
+      KSEF_TOKEN_ENCRYPTION = "KsefTokenEncryption"
+      SYMMETRIC_KEY_ENCRYPTION = "SymmetricKeyEncryption"
+      USAGES = [KSEF_TOKEN_ENCRYPTION, SYMMETRIC_KEY_ENCRYPTION].freeze
+
+      def self.from(payload)
+        new(
+          certificate: payload["certificate"],
+          certificate_id: payload["certificateId"],
+          public_key_id: payload["publicKeyId"],
+          valid_from: time(payload["validFrom"]),
+          valid_to: time(payload["validTo"]),
+          usage: Array(payload["usage"]).freeze
+        )
+      end
+
+      # Parsed strictly here, unlike {Ksef::Auth.time}'s informational timestamps: these
+      # two bound the window in which the key may be used, so an unparseable value must
+      # not read as "no constraint". It becomes `nil`, and {#valid_at?} then refuses the
+      # certificate outright — fail closed, since sending a payload wrapped with a lapsed
+      # key is worse than declining to send one.
+      def self.time(value)
+        return value if value.is_a?(Time)
+
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+      private_class_method :time
+
+      # @param kind [String] one of {USAGES}
+      def usable_for?(kind) = usage.include?(kind)
+
+      def valid_at?(now = Time.now)
+        return false if valid_from.nil? || valid_to.nil?
+
+        now.between?(valid_from, valid_to)
+      end
+
+      # The contract ships the certificate as **DER, base64-encoded, without PEM armour**,
+      # so it cannot be handed to OpenSSL as text.
+      #
+      # Not memoised: `Data` instances are frozen, and this is called once per session
+      # open or authentication, where a DER parse is not worth caching around.
+      #
+      # @return [OpenSSL::X509::Certificate]
+      def x509 = OpenSSL::X509::Certificate.new(Crypto.decode(certificate))
+
+      # @return [OpenSSL::PKey::RSA]
+      def public_key = x509.public_key
+
+      # RSA-OAEP under this certificate's key. The plaintexts KSeF asks for are a 32-byte
+      # symmetric key (§10.1) and a short `token|timestamp` string (§4.5), both far inside
+      # {Crypto::MAX_OAEP_PLAINTEXT_BYTES}.
+      #
+      # @return [String] raw ciphertext; base64 it with {Crypto.encode} before sending
+      def encrypt(plaintext) = Crypto.rsa_encrypt(plaintext, public_key)
+    end
+  end
+end