ksef-client-rails 0.1.0 → 1.0.0

data/lib/ksef/crypto/csr.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Ksef
+  module Crypto
+    # PKCS#10 CSR generator for KSeF certificate enrollment.
+    #
+    # The DN comes from `GET /certificates/enrollments/data`; RDN order and ASN.1 types mirror C#
+    # `CreateSubjectDistinguishedName` (see {SUBJECT_FIELDS}). RSA signing uses PKCS#1 v1.5
+    # (Java's choice, not C#'s PSS); EC P-256 is the recommended key.
+    module Csr
+      # RDN order: [OID, response field method, ASN.1 type].
+      SUBJECT_FIELDS = [
+        ["2.5.4.3",  "commonName",             OpenSSL::ASN1::UTF8STRING],
+        ["2.5.4.4",  "surname",                OpenSSL::ASN1::UTF8STRING],
+        ["2.5.4.42", "givenName",              OpenSSL::ASN1::UTF8STRING],
+        ["2.5.4.10", "organizationName",       OpenSSL::ASN1::UTF8STRING],
+        ["2.5.4.97", "organizationIdentifier", OpenSSL::ASN1::UTF8STRING],
+        ["2.5.4.6",  "countryName",            OpenSSL::ASN1::PRINTABLESTRING],
+        ["2.5.4.5",  "serialNumber",           OpenSSL::ASN1::PRINTABLESTRING],
+        ["2.5.4.45", "uniqueIdentifier",       OpenSSL::ASN1::UTF8STRING]
+      ].freeze
+
+      # CSR generation result: the request plus the private key (both Base64/PEM).
+      Result = Struct.new(:csr_der_base64, :private_key, keyword_init: true) do
+        # @return [String] private key in PEM format
+        def private_key_pem
+          private_key.to_pem
+        end
+
+        # @return [String] private key in DER, Base64-encoded (as in the SDKs)
+        def private_key_der_base64
+          Base64.strict_encode64(private_key.to_der)
+        end
+
+        # The private key never goes to error pages, `pp` output or exception reports.
+        # @return [String]
+        def inspect
+          "#<#{self.class.name} csr_der_base64=#{csr_der_base64.inspect} private_key=[REDACTED]>"
+        end
+        alias_method :to_s, :inspect
+
+        # `pp` and IRB print through #pretty_print, which Struct implements without calling #inspect.
+        def pretty_print(printer)
+          printer.text(inspect)
+        end
+      end
+
+      module_function
+
+      # Generates a CSR with an RSA-2048 key (SHA256 PKCS#1 v1.5 signature).
+      # @param enrollment_data [Hash] the /certificates/enrollments/data response
+      # @return [Result]
+      def generate_rsa(enrollment_data)
+        key = OpenSSL::PKey::RSA.new(2048)
+        build_request(enrollment_data, key)
+      end
+
+      # Generates a CSR with an EC P-256 key (recommended; ECDSA-SHA256 signature).
+      # @param enrollment_data [Hash] the /certificates/enrollments/data response
+      # @return [Result]
+      def generate_ecdsa(enrollment_data)
+        key = OpenSSL::PKey::EC.generate("prime256v1")
+        build_request(enrollment_data, key)
+      end
+
+      # Builds and signs the CSR with the given key.
+      # @param enrollment_data [Hash]
+      # @param key [OpenSSL::PKey::PKey]
+      # @return [Result]
+      def build_request(enrollment_data, key)
+        request = OpenSSL::X509::Request.new
+        request.version = 0
+        request.subject = build_subject(enrollment_data)
+        request.public_key = public_key_of(key)
+        request.sign(key, OpenSSL::Digest.new("SHA256"))
+
+        Result.new(csr_der_base64: Base64.strict_encode64(request.to_der), private_key: key)
+      end
+
+      # Builds the DN preserving order and ASN.1 types (empty fields are skipped).
+      # @param data [Hash]
+      # @return [OpenSSL::X509::Name]
+      def build_subject(data)
+        name = OpenSSL::X509::Name.new
+        SUBJECT_FIELDS.each do |oid, field, asn1_type|
+          value = data[field] || data[field.to_sym]
+          next if value.nil? || value.to_s.empty?
+
+          name.add_entry(oid, value.to_s, asn1_type)
+        end
+        name
+      end
+
+      # Extracts the public key (SPKI) regardless of type (RSA/EC).
+      # On OpenSSL 3.0 keys are immutable, so we round-trip through DER SubjectPublicKeyInfo.
+      # @param key [OpenSSL::PKey::PKey]
+      # @return [OpenSSL::PKey::PKey] a key holding only the public part
+      def public_key_of(key)
+        OpenSSL::PKey.read(key.public_to_der)
+      end
+    end
+  end
+end

data/lib/ksef/crypto/public_keys.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "time"
+
+module Ksef
+  module Crypto
+    # Fetches, caches and selects the Ministry of Finance public-key certificates by usage
+    # (`GET /security/public-key-certificates`, anonymous). {#with_rotation_retry} refreshes them
+    # on error 21470 — both SDKs leave that refresh to the caller.
+    class PublicKeys
+      # Certificate usages (values of the PublicKeyCertificateUsage enum).
+      SYMMETRIC_KEY_ENCRYPTION = "SymmetricKeyEncryption"
+      KSEF_TOKEN_ENCRYPTION = "KsefTokenEncryption"
+      # API error code: the data was encrypted under a certificate that has since been rotated.
+      KEY_ROTATED = 21_470
+
+      ENDPOINT = "/security/public-key-certificates"
+
+      # A single Ministry of Finance public-key certificate.
+      Certificate = Struct.new(:certificate_der, :certificate_id, :public_key_id,
+                               :valid_from, :valid_to, :usages, keyword_init: true) do
+        # @param usage [String]
+        # @return [Boolean] whether the certificate may be used for the given usage
+        def usable_for?(usage)
+          usages.include?(usage)
+        end
+
+        # @param time [Time]
+        # @return [Boolean] whether the certificate is valid at the given moment
+        def valid_at?(time)
+          valid_from <= time && time < valid_to
+        end
+
+        # @return [OpenSSL::X509::Certificate] parsed certificate (memoized)
+        def openssl_certificate
+          @openssl_certificate ||= OpenSSL::X509::Certificate.new(certificate_der)
+        end
+
+        # @return [OpenSSL::PKey::PKey] public key (RSA or EC)
+        def public_key
+          openssl_certificate.public_key
+        end
+      end
+
+      # @param connection [Ksef::Http::Connection] HTTP connection (anonymous call)
+      # @param logger [Logger, nil]
+      # @param clock [#call] time source (for tests); defaults to -> { Time.now }
+      def initialize(connection:, logger: nil, clock: -> { Time.now })
+        @connection = connection
+        @logger = logger
+        @clock = clock
+        @cache = nil
+        @mutex = Mutex.new
+      end
+
+      # Returns the certificate list (cached; fetched on first call or when +force+).
+      # @param force [Boolean] force a refetch
+      # @return [Array<Certificate>]
+      def all(force: false)
+        @mutex.synchronize do
+          @cache = fetch_certificates if force || @cache.nil?
+          @cache
+        end
+      end
+
+      # Picks the newest valid RSA certificate for the given usage — the gem wraps keys and tokens with
+      # RSA-OAEP only. When the cached list has none (the cache outlived a rotation in a long-running
+      # process), it refetches once before giving up.
+      # @param usage [String] SYMMETRIC_KEY_ENCRYPTION or KSEF_TOKEN_ENCRYPTION
+      # @return [Certificate]
+      # @raise [Ksef::CryptoError] when no valid certificate is available
+      def for_usage(usage)
+        select_certificate(usage) || select_certificate(usage, force: true) ||
+          raise(CryptoError, "No valid Ministry of Finance RSA certificate for usage: #{usage}")
+      end
+
+      # Forces a refetch of the certificates (e.g. after rotation error 21470).
+      # @return [Array<Certificate>]
+      def refresh!
+        @logger&.info("[ksef] refreshing Ministry of Finance public-key certificates (rotation)")
+        all(force: true)
+      end
+
+      # Runs the block; when the API answers 21470, refetches the certificates and runs it once more
+      # with +true+, so the caller re-encrypts with the new key.
+      # @yieldparam retrying [Boolean]
+      # @return [Object] the block's result
+      def with_rotation_retry
+        yield(false)
+      rescue ApiError => e
+        raise unless e.codes.include?(KEY_ROTATED)
+
+        refresh!
+        yield(true)
+      end
+
+      private
+
+      def select_certificate(usage, force: false)
+        now = @clock.call
+        all(force: force)
+          .select { |c| c.usable_for?(usage) && c.valid_at?(now) && c.public_key.is_a?(OpenSSL::PKey::RSA) }
+          .max_by(&:valid_from)
+      end
+
+      def fetch_certificates
+        response = @connection.get(ENDPOINT)
+        Array(response.body).map { |item| build_certificate(item) }
+      end
+
+      def build_certificate(item)
+        Certificate.new(
+          certificate_der: Base64.decode64(item["certificate"]),
+          certificate_id: item["certificateId"],
+          public_key_id: item["publicKeyId"],
+          valid_from: Time.iso8601(item["validFrom"]),
+          valid_to: Time.iso8601(item["validTo"]),
+          usages: Array(item["usage"])
+        )
+      end
+    end
+  end
+end

data/lib/ksef/environments.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Ksef
+  # The public KSeF environments, each with its API and QR host.
+  #
+  # The path prefix is `/v2`, as in both SDKs — the `/api/v2` seen in the docs is an
+  # OpenAPI generator artifact, not a real path.
+  module Environments
+    # A single environment: API and QR base URLs plus metadata.
+    Environment = Struct.new(:key, :api_base_url, :qr_base_url, :api_path_prefix, :description, keyword_init: true) do
+      # @return [String] full base URL for API requests (including the version prefix), no trailing "/"
+      def request_base_url
+        "#{api_base_url}#{api_path_prefix}"
+      end
+    end
+
+    # Test (Release Candidate). Allows self-signed certificates for authentication.
+    # Data is NOT isolated between integrators — use random tax identification numbers.
+    TEST = Environment.new(
+      key: :test,
+      api_base_url: "https://api-test.ksef.mf.gov.pl",
+      qr_base_url: "https://qr-test.ksef.mf.gov.pl",
+      api_path_prefix: "/v2",
+      description: "Test environment (RC) — self-signed allowed, shared data"
+    ).freeze
+
+    # Pre-production (Demo) — configuration close to production.
+    DEMO = Environment.new(
+      key: :demo,
+      api_base_url: "https://api-demo.ksef.mf.gov.pl",
+      qr_base_url: "https://qr-demo.ksef.mf.gov.pl",
+      api_path_prefix: "/v2",
+      description: "Pre-production environment (Demo)"
+    ).freeze
+
+    # Production — invoices with full legal effect.
+    PROD = Environment.new(
+      key: :prod,
+      api_base_url: "https://api.ksef.mf.gov.pl",
+      qr_base_url: "https://qr.ksef.mf.gov.pl",
+      api_path_prefix: "/v2",
+      description: "Production environment"
+    ).freeze
+
+    ALL = { test: TEST, demo: DEMO, prod: PROD }.freeze
+
+    # Returns an environment by key (:test/:demo/:prod), or passes through a ready object.
+    #
+    # @param key_or_env [Symbol, String, Environment]
+    # @return [Environment]
+    # @raise [Ksef::ConfigurationError] when the key is unknown
+    def self.fetch(key_or_env)
+      return key_or_env if key_or_env.is_a?(Environment)
+
+      key = key_or_env.to_s.downcase.to_sym
+      ALL.fetch(key) do
+        raise ConfigurationError, "Unknown KSeF environment: #{key_or_env.inspect} (allowed: #{ALL.keys.join(', ')})"
+      end
+    end
+  end
+end

data/lib/ksef/errors.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Ksef
+  # Base error of the gem; every error below inherits from it.
+  #
+  # 450/460/470/480/550 are NOT HTTP codes — they are `status.code` values inside an HTTP 200
+  # body, hence AuthenticationFailed is a separate branch rather than an ApiError subclass.
+  class Error < StandardError; end
+
+  # Invalid gem configuration detected locally (e.g. missing environment, bad base_url).
+  class ConfigurationError < Error; end
+
+  # Cryptography / XAdES signature layer error (e.g. no private key in the certificate).
+  class CryptoError < Error; end
+
+  # Error returned by the API as an HTTP 4xx/5xx response. {Ksef::Http::ErrorParser} fills the
+  # attributes from either response format (legacy `exceptionDetailList[]` or RFC 7807).
+  class ApiError < Error
+    # @return [Integer, nil] HTTP status code (e.g. 400, 429)
+    attr_reader :status
+    # @return [Array<Integer>] business error codes from the body (e.g. [21402])
+    attr_reader :codes
+    # @return [String, nil] trace identifier (trace_id / traceId), when returned
+    attr_reader :trace_id
+    # @return [Array<Hash>] raw error entries (for diagnostics)
+    attr_reader :details
+    # @return [Object, nil] raw parsed response body
+    attr_reader :body
+
+    # @param message [String, nil] human-readable message
+    # @param status [Integer, nil] HTTP code
+    # @param codes [Array<Integer>] business error codes
+    # @param trace_id [String, nil]
+    # @param details [Array<Hash>] raw error entries
+    # @param body [Object, nil] raw response body
+    def initialize(message = nil, status: nil, codes: [], trace_id: nil, details: [], body: nil)
+      @status = status
+      @codes = Array(codes)
+      @trace_id = trace_id
+      @details = Array(details)
+      @body = body
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(message)
+      parts = []
+      parts << "HTTP #{status}" if status
+      parts << (message || "KSeF API error")
+      parts << "codes: #{codes.join(', ')}" unless codes.empty?
+      parts << "trace_id: #{trace_id}" if trace_id
+      parts.join(" | ")
+    end
+  end
+
+  # 400 — invalid request (validation, wrong schema, wrong invoice sizes/hashes).
+  class BadRequest < ApiError; end
+
+  # 400 with code 21184 — the session is under maintenance. Retry later, or open a new session and
+  # send the remaining invoices there.
+  class SessionUnavailable < BadRequest; end
+
+  # The authentication can no longer be used — authenticate again: a 400 with code 21301 (the
+  # authentication does not allow it, e.g. its KSeF token was revoked) or 21304 (the authentication
+  # operation does not exist — also from the auth status), or a 401 from the token refresh (the refresh
+  # token expired or was revoked).
+  class ReauthenticationRequired < ApiError; end
+
+  # 401 — missing/invalid authentication token, or the token expired.
+  class Unauthorized < ApiError; end
+
+  # 403 — no permission for the resource in the given context.
+  class Forbidden < ApiError; end
+
+  # 404 — resource does not exist.
+  class NotFound < ApiError; end
+
+  # 410 — resource expired (retention: auth/export 7 days, enrollment/permissions 30 days).
+  class Gone < ApiError; end
+
+  # 409 — conflict (e.g. the operation was already performed).
+  class Conflict < ApiError; end
+
+  # 429 — request limit exceeded. Carries `retry_after` (seconds) from the Retry-After header.
+  class RateLimited < ApiError
+    # @return [Integer, nil] seconds until a retry is allowed (from the Retry-After header)
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **)
+      @retry_after = retry_after
+      super(message, **)
+    end
+  end
+
+  # 5xx — server-side error.
+  class ServerError < ApiError; end
+
+  # KSeF rejected an invoice: a `status.code` of 400 or more in the invoice status (an HTTP 200 body), so
+  # `#status` is nil and the code is in `#codes` (440 — a duplicate); `#body` is that status. Any other
+  # ApiError from waiting for the UPO is not a rejection — the invoice may already be accepted.
+  class InvoiceRejected < ApiError; end
+
+  # Transport failure (DNS, refused connection, TLS, timeout, a dropped connection) once the allowed
+  # retries are spent; the original Faraday exception is the #cause. For a call that is not idempotent
+  # (e.g. sending an invoice) a failure after the request was written — a reset, a dropped or cut-short
+  # response — leaves the outcome unknown, as a {RequestTimeout} does: check the status before sending it
+  # again.
+  class NetworkError < Error; end
+
+  # The request timed out waiting for the response. For a call that is not idempotent the outcome is
+  # unknown — check the status before sending it again. (A request that never left the process, such
+  # as a connect timeout, is a plain {NetworkError}.)
+  class RequestTimeout < NetworkError; end
+
+  # A batch upload failed after the session was declared — a part upload, or closing the session. The
+  # reference number names the session to check (and close again) before uploading anew.
+  class BatchUploadError < Error
+    # @return [String, nil] batch session reference number
+    attr_reader :reference_number
+    # @return [Integer, nil] ordinal number of the part that failed (nil when closing failed)
+    attr_reader :ordinal_number
+
+    def initialize(message = nil, reference_number: nil, ordinal_number: nil)
+      @reference_number = reference_number
+      @ordinal_number = ordinal_number
+      super([message, ("session: #{reference_number}" if reference_number)].compact.join(" | "))
+    end
+  end
+
+  # Auth failed — `status.code` from the polling body signalled an error (450 invalid token,
+  # 460 certificate, 470 deceased person, 480 blocked, 425 revoked, 415 no permissions, 550 cancelled).
+  class AuthenticationFailed < Error
+    # @return [Integer, nil] the status.code value from the response body (e.g. 450)
+    attr_reader :code
+    # @return [Array<String>] detailed messages (status.details)
+    attr_reader :messages
+
+    def initialize(message = nil, code: nil, messages: [])
+      @code = code
+      @messages = Array(messages)
+      super([message, "status.code=#{code}", *messages].compact.join(" | "))
+    end
+  end
+
+  # Invoice failed local validation ({Ksef::Invoices::Validator}): the XSD or KSeF's XML rules, which KSeF
+  # would reject too (in libxml2's wording).
+  class SchemaValidationError < Error
+    # @return [Array<String>] XSD validator messages
+    attr_reader :messages
+    # @return [Array<Ksef::Invoices::Validator::Issue>] the same violations with element path and line
+    attr_reader :errors
+    # @return [String, nil] form systemCode (e.g. "FA (3)")
+    attr_reader :system_code
+
+    def initialize(message = nil, messages: [], errors: [], system_code: nil)
+      @messages = Array(messages)
+      @errors = Array(errors)
+      @system_code = system_code
+      super([message, *@messages].compact.join(" | "))
+    end
+  end
+
+  # A metadata query reached KSeF's 10,000-record limit (`hasMore` and `isTruncated`): the rest is
+  # fetched with a narrower `dateRange` bounded by the last record's date — `from` when sorted ascending,
+  # `to` when descending.
+  class ResultTruncated < Error
+    # @return [Hash, nil] the last record returned — its date is where the next query starts
+    attr_reader :last_item
+
+    def initialize(message = nil, last_item: nil)
+      @last_item = last_item
+      super(message)
+    end
+  end
+
+  # Async operation (auth, session, export, enrollment, permissions) exceeded its wait limit.
+  class PollingTimeout < Error
+    # @return [String, nil] last known status of the operation
+    attr_reader :last_status
+
+    def initialize(message = nil, last_status: nil)
+      @last_status = last_status
+      super([message, ("last status: #{last_status}" if last_status)].compact.join(" | "))
+    end
+  end
+end