ksef_client 0.1.0.rc1 → 0.1.0

data/lib/ksef/auth/signature_template.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Ksef
+  module Auth
+    # Renders the `ds:Signature` element, with the `SignedProperties` digest and the
+    # `SignatureValue` left empty for {Signer} to fill in once they can be computed.
+    #
+    # Separated from {Signer} because the two jobs are genuinely different: this one is
+    # string templating with fiddly namespace placement, the other is canonicalising,
+    # digesting and signing. Rendering from a template rather than assembling nodes is
+    # deliberate — the prefixed and default-namespaced elements interleave, and the
+    # equivalent Nokogiri namespace calls are markedly harder to read and to get right.
+    class SignatureTemplate
+      include Xades
+
+      def initialize(certificate:, signing_time:)
+        @certificate = certificate
+        @signing_time = signing_time
+      end
+
+      # @param document_digest [String] Base64 SHA-256 over the canonicalised document
+      # @return [String] the signature element, ready to be parsed and adopted
+      def render(document_digest)
+        <<~XML
+          <ds:Signature xmlns:ds="#{DS}" Id="#{SIGNATURE_ID}">
+            <ds:SignedInfo>
+              <ds:CanonicalizationMethod Algorithm="#{CANONICALIZATION}"/>
+              <ds:SignatureMethod Algorithm="#{SIGNATURE_METHOD}"/>
+          #{document_reference(document_digest)}
+          #{signed_properties_reference}
+            </ds:SignedInfo>
+            <ds:SignatureValue/>
+            <ds:KeyInfo>
+              <ds:X509Data>
+                <ds:X509Certificate>#{encode(certificate.to_der)}</ds:X509Certificate>
+              </ds:X509Data>
+            </ds:KeyInfo>
+            <ds:Object>#{qualifying_properties}</ds:Object>
+          </ds:Signature>
+        XML
+      end
+
+      private
+
+      attr_reader :certificate, :signing_time
+
+      # `URI=""` means the whole document; the enveloped-signature transform then removes
+      # this signature from it, and exclusive c14n normalises what is left. Order matters.
+      def document_reference(digest)
+        <<~XML.chomp
+          <ds:Reference URI="">
+            <ds:Transforms>
+              <ds:Transform Algorithm="#{ENVELOPED_SIGNATURE}"/>
+              <ds:Transform Algorithm="#{CANONICALIZATION}"/>
+            </ds:Transforms>
+            <ds:DigestMethod Algorithm="#{DIGEST_METHOD}"/>
+            <ds:DigestValue>#{digest}</ds:DigestValue>
+          </ds:Reference>
+        XML
+      end
+
+      def signed_properties_reference
+        <<~XML.chomp
+          <ds:Reference Type="#{SIGNED_PROPERTIES_TYPE}" URI="##{SIGNED_PROPERTIES_ID}">
+            <ds:Transforms>
+              <ds:Transform Algorithm="#{CANONICALIZATION}"/>
+            </ds:Transforms>
+            <ds:DigestMethod Algorithm="#{DIGEST_METHOD}"/>
+            <ds:DigestValue/>
+          </ds:Reference>
+        XML
+      end
+
+      # `xmlns="#{DS}"` is deliberate, and matches the reference implementation: the
+      # qualifying properties mix `xades:`-prefixed elements with xmldsig ones written
+      # unprefixed, so `DigestMethod` and `DigestValue` here are in the *xmldsig* namespace
+      # despite sitting inside `xades:CertDigest`. Getting that wrong yields a document
+      # that looks right and verifies nowhere.
+      def qualifying_properties
+        <<~XML.strip
+          <xades:QualifyingProperties xmlns:xades="#{XADES}" xmlns="#{DS}" Target="##{SIGNATURE_ID}">
+                <xades:SignedProperties Id="#{SIGNED_PROPERTIES_ID}">
+                  <xades:SignedSignatureProperties>
+                    <xades:SigningTime>#{signing_time}</xades:SigningTime>
+          #{signing_certificate}
+                  </xades:SignedSignatureProperties>
+                </xades:SignedProperties>
+              </xades:QualifyingProperties>
+        XML
+      end
+
+      def signing_certificate
+        <<~XML.chomp
+          <xades:SigningCertificate>
+            <xades:Cert>
+              <xades:CertDigest>
+                <DigestMethod Algorithm="#{DIGEST_METHOD}"/>
+                <DigestValue>#{encode(OpenSSL::Digest::SHA256.digest(certificate.to_der))}</DigestValue>
+              </xades:CertDigest>
+              <xades:IssuerSerial>
+                <X509IssuerName>#{issuer_name}</X509IssuerName>
+                <X509SerialNumber>#{certificate.serial}</X509SerialNumber>
+              </xades:IssuerSerial>
+            </xades:Cert>
+          </xades:SigningCertificate>
+        XML
+      end
+
+      # RFC 2253 orders attributes most-specific-first, which is what .NET's
+      # `X509Certificate2.Issuer` produces — so a signature from either client describes the
+      # same issuer the same way.
+      def issuer_name = certificate.issuer.to_s(OpenSSL::X509::Name::RFC2253)
+
+      # `pack("m0")` rather than the base64 library: no line breaks, no dependency.
+      def encode(bytes) = [bytes].pack("m0")
+    end
+  end
+end

data/lib/ksef/auth/signer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "openssl"
+
+module Ksef
+  module Auth
+    # Produces the XAdES-BES enveloped signature that `POST /auth/xades-signature`
+    # requires (docs/REFERENCE.md §4.3).
+    #
+    # The algorithms come from {Xades} and the XML from {SignatureTemplate}; what lives here
+    # is the part that has to be exactly right — what gets canonicalised, in what order, and
+    # over which bytes.
+    #
+    # ## Why this signs a String and returns a String
+    #
+    # A digest over "the document" has to match what the *verifier* computes after parsing
+    # the bytes we send. Nokogiri's `to_xml` pretty-prints on output without adding text
+    # nodes to the tree, so an in-memory tree and its serialised form can canonicalise
+    # differently — the classic XML-DSig footgun. Signing the serialised bytes and emitting
+    # them without reformatting removes the discrepancy entirely. `ksef-client-csharp` deals
+    # with the same problem by setting `PreserveWhitespace = true`.
+    class Signer
+      include Xades
+
+      # Emit exactly the bytes that were signed: `AS_XML` alone excludes `FORMAT`, so
+      # nothing is re-indented. Passing the default would silently invalidate every
+      # signature this produces.
+      SAVE_OPTIONS = Nokogiri::XML::Node::SaveOptions::AS_XML
+
+      # `SigningTime` is backdated by a minute, lifted from `ksef-client-csharp`'s
+      # `CertificateTimeBuffer = TimeSpan.FromMinutes(-1)`. It is unexplained there but is
+      # plainly a clock-skew guard: a signing time fractionally in the future relative to
+      # the server's clock invites rejection, and being a minute early costs nothing.
+      CLOCK_SKEW_SECONDS = 60
+
+      attr_reader :certificate
+
+      # @param certificate [OpenSSL::X509::Certificate] must meet the subject requirements
+      #   of §4.4
+      # @param key [OpenSSL::PKey::RSA] its private key
+      # @param signing_time [Time, nil] override, for deterministic tests
+      # @param clock_skew [Integer] seconds to backdate `SigningTime` by
+      def initialize(certificate:, key:, signing_time: nil, clock_skew: CLOCK_SKEW_SECONDS)
+        @certificate = certificate
+        @key = key
+        @signing_time = signing_time
+        @clock_skew = clock_skew
+        verify_key_matches_certificate
+      end
+
+      # @param input [String, #to_xml] the unsigned `AuthTokenRequest`
+      # @param validate [Boolean] check against the auth schema first. On by default:
+      #   signing is expensive and a malformed document is cheap to catch. It has to happen
+      #   *before* signing, because a signed document can never be schema-valid (§14.5) —
+      #   the schema's sequence has no `xsd:any`, so the very signature the API demands
+      #   counts as an unexpected element.
+      # @return [String] the document with a `ds:Signature` appended to its root
+      # @raise [Ksef::ValidationError]
+      def sign(input, validate: true)
+        xml = input.respond_to?(:to_xml) ? input.to_xml : input.to_s
+        document = Nokogiri::XML(xml)
+        raise ValidationError, "Cannot sign: the document has no root element" if document.root.nil?
+
+        # `TokenRequest` knows whether its own context type can be meaningfully validated
+        # (§14.4: two of the four have defective upstream patterns), and carries the advisory
+        # explaining a failure that is not the caller's fault. Delegating to it means a
+        # `NipVatUe` or `PeppolId` request fails with the reason rather than a bare schema
+        # error — and can still be signed with `validate: false`, which is the resolution
+        # §14.4 arrived at.
+        validate!(input, xml) if validate
+
+        # Computed before the signature exists, which is exactly what the
+        # enveloped-signature transform reproduces for the verifier.
+        document.root.add_child(signature_for(digest(document.canonicalize(C14N_MODE))))
+        seal(document)
+        document.to_xml(save_with: SAVE_OPTIONS)
+      end
+
+      private
+
+      # The template declares every namespace it uses, so it needs no ancestor context and
+      # `add_child` can adopt it straight from its own document.
+      def signature_for(document_digest)
+        template = SignatureTemplate.new(certificate: certificate, signing_time: signing_time)
+        Nokogiri::XML(template.render(document_digest)).root
+      end
+
+      # Order is not optional. `SignedProperties` must be digested in its final position —
+      # exclusive c14n pulls in the namespace declarations it inherits — and `SignedInfo`
+      # can only be signed once both of its digests are in place.
+      def seal(document)
+        properties = at(document, "//xades:SignedProperties")
+        at(document, "//ds:Reference[@Type]/ds:DigestValue").content =
+          digest(properties.canonicalize(C14N_MODE))
+
+        signed_info = at(document, "//ds:SignedInfo")
+        at(document, "//ds:SignatureValue").content =
+          encode(@key.sign("SHA256", signed_info.canonicalize(C14N_MODE)))
+      end
+
+      # Uses the request's own advisory when there is one, so the error names the upstream
+      # defect instead of implying bad input.
+      def validate!(input, xml)
+        return input.validate! if input.respond_to?(:validate!)
+
+        Validator.validate!(xml)
+      end
+
+      def at(document, xpath)
+        document.at_xpath(xpath, XPATH_NAMESPACES) ||
+          raise(ValidationError, "Malformed signature template: #{xpath} not found")
+      end
+
+      def signing_time
+        ((@signing_time || Time.now).utc - @clock_skew).strftime("%Y-%m-%dT%H:%M:%SZ")
+      end
+
+      def digest(bytes) = encode(OpenSSL::Digest::SHA256.digest(bytes))
+
+      def encode(bytes) = [bytes].pack("m0")
+
+      # Signing with a mismatched key yields a perfectly well-formed document that fails
+      # only at the far end, with an error that will not say why.
+      def verify_key_matches_certificate
+        return if certificate.check_private_key(@key)
+
+        raise ValidationError, "The private key does not match the certificate's public key"
+      end
+    end
+  end
+end

data/lib/ksef/auth/status.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # Status codes returned by `GET /auth/{referenceNumber}` in `StatusInfo.code`.
+    #
+    # These are *not* HTTP statuses — they travel inside a 200 response and describe the
+    # asynchronous authentication operation.
+    #
+    # **Sourced from the pinned OpenAPI contract**, whose
+    # `AuthenticationOperationStatusResponse.status` description carries the complete table
+    # (docs/REFERENCE.md §4.8). An earlier revision credited
+    # `AuthenticationStatusCodeResponse.cs` in `ksef-client-csharp` and treated the list as a
+    # reference-implementation constant. That understated it: the contract is a first-tier
+    # artifact, and reading it added {BLOCKED} — which the C# list does not have — while
+    # showing that `400` and `401` are C#-only and not contract codes at all.
+    module Status
+      IN_PROGRESS = 100
+      SUCCESS = 200
+      NO_PERMISSIONS = 415
+      REVOKED = 425
+      TOKEN_ERROR = 450
+      CERTIFICATE_ERROR = 460
+      DECEASED_USER = 470
+      BLOCKED = 480
+      UNKNOWN_ERROR = 500
+      CANCELLED = 550
+
+      # Present in `ksef-client-csharp`'s enum but **not** in the contract's table. Kept
+      # because the server may still send them and a named constant beats a bare integer,
+      # but do not treat their absence from the contract as an oversight on our part.
+      BAD_REQUEST = 400
+      UNAUTHORIZED = 401
+
+      # Several distinct causes share one code — the contract lists **eight** distinct 450
+      # details (a malformed, mistimed, revoked or inactive token, plus a bad challenge, bad
+      # encryption, bad encoding, and a token unusable in the requested context) and six for
+      # 460. The distinction arrives only in `StatusInfo#description`, which is why
+      # {OperationStatus#explain} prefers the server's wording over this table.
+      DESCRIPTIONS = {
+        IN_PROGRESS => "authentication in progress",
+        SUCCESS => "authentication succeeded",
+        BAD_REQUEST => "bad request",
+        UNAUTHORIZED => "unauthorized",
+        NO_PERMISSIONS => "failed: the subject holds no permissions in this context",
+        REVOKED => "authentication and its refresh tokens were revoked",
+        TOKEN_ERROR => "failed: token invalid, mistimed, revoked, inactive, wrongly encrypted or " \
+                       "encoded, or not usable in this context",
+        CERTIFICATE_ERROR => "failed: certificate invalid, untrusted, revoked, suspended or malformed",
+        DECEASED_USER => "failed: authorisation methods of a deceased person",
+        BLOCKED => "blocked: suspected security incident — contact the Ministry of Finance, do not retry",
+        UNKNOWN_ERROR => "unknown error",
+        CANCELLED => "cancelled by the system; retry later"
+      }.freeze
+
+      # The only code that means "keep polling". Anything else is terminal — treating an
+      # unrecognised code as retryable would poll forever against a dead operation.
+      def self.in_progress?(code) = code == IN_PROGRESS
+      def self.success?(code) = code == SUCCESS
+      def self.terminal?(code) = !in_progress?(code)
+
+      # `550` is the system cancelling its own work and inviting a retry, which is a
+      # different proposition from a rejected certificate.
+      def self.retryable?(code) = code == CANCELLED
+
+      def self.describe(code) = DESCRIPTIONS.fetch(code, "unrecognised status code #{code}")
+    end
+  end
+end

data/lib/ksef/auth/token.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # A KSeF token and the context it authenticates into — the credential object of
+    # DESIGN.md §8:
+    #
+    #     Ksef::Auth::Token.new(context_nip: "9999999999", token: ENV["KSEF_TOKEN"])
+    #
+    # A KSeF token is the second of the API's two authentication methods
+    # (docs/REFERENCE.md §4). It is not a bearer token and is never sent as one: it is
+    # RSA-OAEP-encrypted together with the challenge's timestamp and posted to
+    # `POST /auth/ksef-token`, which starts the same asynchronous operation the XAdES flow
+    # does and ends at the same `POST /auth/token/redeem`.
+    #
+    # ## It cannot be the first credential
+    #
+    # A KSeF token can only be *issued* after a one-time XAdES authentication
+    # (`tokeny-ksef.md`; `POST /tokens` requires a bearer, `/auth/xades-signature` requires
+    # nothing). So this class is the everyday path and {Signer} is the bootstrap — which is
+    # why the certificate flow shipped first (§6a.2).
+    #
+    # Treat instances as secrets. `#to_s` and `#inspect` are redacted, and the token is
+    # reachable only by the deliberate {#authentication_request}.
+    class Token
+      REDACTED = "[REDACTED]"
+
+      # Only two of the contract's four `AuthenticationContextIdentifierType` values are
+      # reachable here, and that is not a simplification: `tokeny-ksef.md` records that a
+      # token can only be issued in a `Nip` or `InternalId` context, so a token for the
+      # other two cannot exist to be presented (§4.1).
+      CONTEXT_TYPES = { nip: "Nip", internal_id: "InternalId" }.freeze
+
+      attr_reader :context_type, :context_value
+
+      # @param token [String] the KSeF token, verbatim from `POST /tokens`
+      # @param context_nip [String, nil] the NIP to authenticate into
+      # @param internal_id [String, nil] an `InternalId` context instead — `<nip>-<5 digits>`
+      # @raise [Ksef::ValidationError] on a missing token, or on neither/both contexts
+      def initialize(token:, context_nip: nil, internal_id: nil)
+        @token = validate_token(token)
+        @context_type, @context_value = resolve_context(context_nip, internal_id)
+        freeze
+      end
+
+      # The contract's `AuthenticationContextIdentifier`.
+      def context_identifier = { type: CONTEXT_TYPES.fetch(context_type), value: context_value }
+
+      # The `InitTokenAuthenticationRequest` body for `POST /auth/ksef-token`.
+      #
+      # Built here rather than inside {Client} for the same reason {Client#submit_xades}
+      # takes an already-signed document: the HTTP layer maps requests and responses, and
+      # the credential is what knows how to present itself.
+      #
+      # @param challenge [Challenge] the whole object, not just its string — see
+      #   {#encrypted_token} for why the timestamp cannot be supplied locally
+      # @param certificate [Ksef::Crypto::Certificate] from
+      #   {Ksef::Crypto::PublicKeys#token_encryption}
+      # @param allowed_ips [Hash, AuthorizationPolicy, nil] optional whitelist restricting
+      #   which client IPs may use the resulting access token
+      # @return [Hash]
+      def authentication_request(challenge:, certificate:, allowed_ips: nil)
+        request = {
+          challenge: Challenge.validate_format!(challenge.to_s),
+          contextIdentifier: context_identifier,
+          encryptedToken: encrypted_token(challenge: challenge, certificate: certificate),
+          publicKeyId: certificate.public_key_id
+        }
+        policy = AuthorizationPolicy.coerce(allowed_ips)
+        policy ? request.merge(authorizationPolicy: { allowedIps: policy.to_h }) : request
+      end
+
+      # `{ksefToken}|{timestampMs}`, UTF-8, RSA-OAEP-encrypted and base64-encoded (§4.5).
+      #
+      # The timestamp is **not** decoration and **not** ours to generate: the docs are
+      # explicit that it acts as a nonce, so that a captured ciphertext cannot be replayed
+      # into a later session. It has to be the `timestampMs` the challenge response
+      # carried, which is why this takes a {Challenge} and not a String — a locally
+      # generated millisecond count will not match, and the authentication fails with
+      # nothing to point at.
+      #
+      # @return [String] base64
+      def encrypted_token(challenge:, certificate:)
+        timestamp = challenge.respond_to?(:timestamp_ms) ? challenge.timestamp_ms : nil
+        if timestamp.nil?
+          raise AuthenticationError,
+                "The KSeF-token flow needs the challenge's own timestampMs, so pass the " \
+                "Ksef::Auth::Challenge returned by POST /auth/challenge rather than its string. " \
+                "The timestamp is a replay nonce (docs/REFERENCE.md §4.5)."
+        end
+
+        Crypto.encode(certificate.encrypt("#{@token}|#{timestamp}"))
+      end
+
+      def to_s = REDACTED
+
+      def inspect
+        "#<Ksef::Auth::Token context=#{CONTEXT_TYPES.fetch(context_type)}:#{context_value} token=#{REDACTED}>"
+      end
+
+      private
+
+      def validate_token(value)
+        return value if value.is_a?(String) && !value.empty?
+
+        raise ValidationError,
+              "A KSeF token is required, got #{value.inspect}. It is issued by POST /tokens after a " \
+              "one-time XAdES authentication (docs/REFERENCE.md §6a.2)."
+      end
+
+      def resolve_context(nip, internal_id)
+        given = { nip: nip, internal_id: internal_id }.compact
+        return given.first if given.size == 1
+
+        raise ValidationError,
+              "Pass exactly one of context_nip: or internal_id:, got #{given.keys.inspect}. " \
+              "A KSeF token exists only in a Nip or InternalId context (docs/REFERENCE.md §4.1)."
+      end
+    end
+  end
+end

data/lib/ksef/auth/token_info.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # A JWT and its expiry, the contract's `TokenInfo` (docs/REFERENCE.md §4.2).
+    TokenInfo = Data.define(:token, :valid_until)
+
+    # Reopened rather than using a `Data.define` block so `REDACTED` lands on the class.
+    class TokenInfo
+      REDACTED = "[REDACTED]"
+
+      def self.from(payload)
+        return nil if payload.nil?
+
+        new(token: payload["token"], valid_until: Ksef::Auth.time(payload["validUntil"]))
+      end
+
+      def expired?(now = Time.now) = !valid_until.nil? && valid_until <= now
+
+      # Both redacted, and `#to_s` deliberately so: these are bearer credentials, and
+      # returning the raw JWT here would make `"...#{token_info}"` in any log line leak a
+      # live one (DESIGN.md §4.5). Reaching for the value is an explicit `#token` call.
+      def to_s = REDACTED
+      def inspect = "#<data Ksef::Auth::TokenInfo token=#{REDACTED} valid_until=#{valid_until.inspect}>"
+    end
+  end
+end

data/lib/ksef/auth/token_request.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ksef
+  module Auth
+    # The `AuthTokenRequest` document — step 2 of the authentication flow
+    # (docs/REFERENCE.md §4.2). Built here, then XAdES-signed and submitted to
+    # `POST /auth/xades-signature`. {#document} exposes the mutable tree because an
+    # enveloped signature has to be inserted *into* the document — {Signer} cannot assemble
+    # a signed request from a string afterwards.
+    #
+    # Defaults to the **2.0** namespace, matching both official clients and every upstream
+    # example; `schema_version:` selects 2.1. See {Ksef::Auth::NAMESPACES} for why, and
+    # §14.4 for why validation nonetheless uses v2.1's rules.
+    class TokenRequest
+      ROOT = "AuthTokenRequest"
+
+      SUBJECT_IDENTIFIER_TYPES = %w[certificateSubject certificateFingerprint].freeze
+
+      # A choice of four, in schema order. The last two cannot hold their real-world values
+      # because of an upstream regex defect (§14.4); they are still offered, because the
+      # server looks up the actual identifier and emitting the absurd value the facet wants
+      # would be worse than failing a local check.
+      CONTEXT_TYPES = %i[nip internal_id nip_vat_ue peppol_id].freeze
+
+      CONTEXT_ELEMENTS = {
+        nip: "Nip", internal_id: "InternalId", nip_vat_ue: "NipVatUe", peppol_id: "PeppolId"
+      }.freeze
+
+      # Context types whose schema pattern is intact, and for which `#validate!` is
+      # therefore meaningful rather than advisory.
+      VALIDATABLE_CONTEXT_TYPES = %i[nip internal_id].freeze
+
+      attr_reader :challenge, :context_type, :context_value, :subject_identifier_type, :allowed_ips,
+                  :namespace, :schema_version
+
+      # @param challenge [String] verbatim from `POST /auth/challenge`
+      # @param context_type [Symbol] one of {CONTEXT_TYPES}
+      # @param context_value [String] the identifier itself
+      # @param subject_identifier_type [String] `"certificateSubject"` or
+      #   `"certificateFingerprint"` — how KSeF should read the signer's identity out of
+      #   the signing certificate (§4.4)
+      # @param allowed_ips [Hash, AuthorizationPolicy, nil] optional client-IP whitelist,
+      #   with any of `:addresses`, `:ranges`, `:masks`
+      # @param schema_version [String] `"2.0"` (default) or `"2.1"`
+      def initialize(challenge:, context_type:, context_value:,
+                     subject_identifier_type: "certificateSubject", allowed_ips: nil,
+                     schema_version: DEFAULT_SCHEMA_VERSION)
+        @namespace = NAMESPACES.fetch(schema_version) do
+          raise ValidationError,
+                "Unknown schema version #{schema_version.inspect}. " \
+                "Expected one of #{NAMESPACES.keys.map(&:inspect).join(", ")}."
+        end
+        @schema_version = schema_version
+        @challenge = Challenge.validate_format!(challenge)
+        @context_type = validate_context_type(context_type)
+        @context_value = context_value
+        @subject_identifier_type = validate_subject_identifier_type(subject_identifier_type)
+        @allowed_ips = AuthorizationPolicy.coerce(allowed_ips)
+        freeze
+      end
+
+      def to_xml
+        document.to_xml(indent: 2, encoding: "UTF-8")
+      end
+
+      # @return [Nokogiri::XML::Document] the unsigned document, for {Signer} to sign in
+      #   place — an enveloped signature has to be added to the tree, not to a string
+      def document
+        Nokogiri::XML::Document.new.tap do |doc|
+          doc.encoding = "UTF-8"
+          root = doc.create_element(ROOT)
+          root.default_namespace = namespace
+          doc.root = root
+
+          add_text(doc, root, "Challenge", challenge)
+          root.add_child(context_element(doc))
+          add_text(doc, root, "SubjectIdentifierType", subject_identifier_type)
+          root.add_child(policy_element(doc)) if allowed_ips
+        end
+      end
+
+      # @raise [Ksef::ValidationError] if the document does not conform to schema v2.1
+      def validate! = Validator.validate!(to_xml, advisory: advisory)
+
+      def valid? = Validator.valid?(to_xml)
+
+      # True when `#validate!` is a real check rather than one the upstream schema cannot
+      # express (§14.4).
+      def validatable? = VALIDATABLE_CONTEXT_TYPES.include?(context_type)
+
+      private
+
+      # Points at the ledger rather than restating the diagnosis, but says enough that the
+      # failure is not mistaken for a bug in the caller's own data.
+      def advisory
+        return "" if validatable?
+
+        "\nNote: the pinned schema's pattern for #{CONTEXT_ELEMENTS[context_type]} is defective upstream " \
+          "(docs/REFERENCE.md §14.4), so this failure may not reflect your input."
+      end
+
+      def context_element(doc)
+        doc.create_element("ContextIdentifier").tap do |node|
+          add_text(doc, node, CONTEXT_ELEMENTS.fetch(context_type), context_value)
+        end
+      end
+
+      def policy_element(doc)
+        doc.create_element("AuthorizationPolicy").tap do |policy|
+          allowed = doc.create_element("AllowedIps")
+          # AllowedIps is mandatory inside the policy, so it is always created; the policy
+          # itself guarantees at least one entry and yields them in schema order.
+          allowed_ips.entries.each { |name, value| add_text(doc, allowed, name, value) }
+          policy.add_child(allowed)
+        end
+      end
+
+      def add_text(doc, parent, name, value)
+        element = doc.create_element(name)
+        element.content = value.to_s
+        parent.add_child(element)
+      end
+
+      def validate_context_type(value)
+        return value if CONTEXT_TYPES.include?(value)
+
+        raise ValidationError,
+              "Unknown context type #{value.inspect}. Expected one of #{CONTEXT_TYPES.map(&:inspect).join(", ")}."
+      end
+
+      def validate_subject_identifier_type(value)
+        return value if SUBJECT_IDENTIFIER_TYPES.include?(value)
+
+        raise ValidationError,
+              "Unknown subject identifier type #{value.inspect}. " \
+              "Expected one of #{SUBJECT_IDENTIFIER_TYPES.map(&:inspect).join(", ")}."
+      end
+    end
+  end
+end

data/lib/ksef/auth/tokens.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # The pair returned by `POST /auth/token/redeem` — the contract's
+    # `AuthenticationTokensResponse`.
+    #
+    # Redemption is **single-use**: a second call with the same authentication token returns
+    # 400 (docs/REFERENCE.md §4.2). Losing this object means repeating the whole flow,
+    # signature included, so it is worth persisting deliberately rather than incidentally.
+    Tokens = Data.define(:access_token, :refresh_token) do
+      def self.from(payload)
+        new(
+          access_token: TokenInfo.from(payload["accessToken"]),
+          refresh_token: TokenInfo.from(payload["refreshToken"])
+        )
+      end
+
+      # Revocation is not immediate: an access token stays valid to its `exp` even after
+      # permissions change (§4.2). Possession is not proof of current authorisation.
+      def expired?(now = Time.now) = access_token.nil? || access_token.expired?(now)
+    end
+  end
+end