facturx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61ac3e80ab256d20b48527e6b92bccd30fcc6f0b7d1b87dec452161fd9e916fb
+  data.tar.gz: 35227d6b843d4c7f51608c2d149b4ce456ca854b16a14ed11317dab0ba2f2cfe
+SHA512:
+  metadata.gz: aa5602b1058a4e5cd06821ea7995d761983b9ddf6cb736e3bcc46e8473230baaf6f215b8f78034f633f19223072b24ce6e474466f5a534801e89516e6d949854
+  data.tar.gz: 3f9504f7f0c04245bd50948d38a1608f1accc18c5bda8dc953229ef60ac4e7cd1071aa15bef81172007e41d6c4eae76cbeaa4999d67d2fb80e52fe9dd00db4da

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-11
+
+### Added
+
+- Validate Factur-X 1.09.2 XML against its profile XSD.
+- Compose PDF/A-3b Factur-X documents with Ghostscript.
+- Extract embedded Factur-X XML from PDF documents.
+
+[Unreleased]: https://github.com/AdVitam/facturx/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/AdVitam/facturx/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2026 AdVitam (https://www.advitam.fr)
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/NOTICE.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+## Factur-X validation schemas
+
+The gem includes Factur-X 1.09.2 / ZUGFeRD 2.5.2 XSD validation artefacts. Their Apache License 2.0 text, provenance, RubyGems packaging adaptation, and file checksums are packaged under `lib/facturx/schema/`.
+
+## Ghostscript
+
+PDF composition invokes a Ghostscript installation supplied by the user. Ghostscript, `zugferd.ps`, and ICC profiles are not part of this gem and remain governed by their respective licences.

data/README.md

@@ -0,0 +1,75 @@
+# facturx
+
+`facturx` validates Factur-X XML, creates PDF/A-3b Factur-X invoices from existing PDFs, and extracts their embedded XML.
+
+The first release supports Factur-X 1.09.2 / ZUGFeRD 2.5.2 with the MINIMUM, BASIC WL, BASIC, EN 16931, and EXTENDED profiles.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem 'facturx'
+```
+
+Then run `bundle install`.
+
+Composition requires Ghostscript 9.54 or newer with `zugferd.ps` and an RGB ICC profile installed on the system. Package contents vary by operating system and distribution: after installing Ghostscript, verify that both resources are present and configure their paths as described below when automatic discovery cannot find them.
+
+## Usage
+
+All inputs and outputs are byte strings. The gem does not interpret strings as file paths.
+
+```ruby
+require 'facturx'
+
+xml = File.binread('invoice.xml')
+pdf = File.binread('invoice.pdf')
+
+Facturx.verify_xml(xml: xml) # => true
+
+facturx_pdf = Facturx.attach(pdf: pdf, xml: xml)
+File.binwrite('invoice-facturx.pdf', facturx_pdf)
+
+embedded_xml = Facturx.extract_xml(pdf: facturx_pdf)
+```
+
+`verify_xml` infers the profile from BT-24 and validates the document against that profile's XSD. It returns `true` on success and raises a typed `Facturx::Error` on failure.
+
+`attach` always validates the XML first. It converts the input PDF to PDF/A-3b, embeds the original XML bytes as `factur-x.xml`, and verifies the resulting attachment and metadata. Signed and encrypted PDFs are rejected because rewriting them would invalidate their protection.
+
+`extract_xml` returns the embedded bytes without validating them. This allows callers to inspect non-conforming invoices received from third parties and explicitly call `verify_xml` when appropriate.
+
+The byte-string API materializes PDF streams in memory. Process untrusted PDFs in a resource-limited worker; limiting only the input file size does not prevent amplification by a compressed embedded stream.
+
+## Ghostscript discovery
+
+The composer searches common installation paths. Override discovery when necessary:
+
+```bash
+export GHOSTSCRIPT_BIN=/opt/ghostscript/bin/gs
+export FACTURX_ZUGFERD_PS=/opt/ghostscript/share/ghostscript/lib/zugferd.ps
+export FACTURX_ICC_PROFILE=/opt/ghostscript/share/ghostscript/iccprofiles/default_rgb.icc
+```
+
+The gem invokes Ghostscript as an external process. It does not distribute Ghostscript, `zugferd.ps`, or ICC profiles.
+
+## Validation scope
+
+Version 0.1 validates XML structure with the official XSDs. It does not yet run the Factur-X Schematron business rules. XSD validation alone must not be presented as complete semantic or regulatory validation.
+
+The gem does not generate invoice XML or the visual invoice PDF, communicate with a PDP, or implement e-reporting.
+
+## Development
+
+```bash
+mise install
+bundle install
+bundle exec rubocop
+bundle exec rspec
+bundle exec rake build
+```
+
+## License
+
+The gem code is available under the MIT License. Bundled standard artefacts retain their respective upstream notices; see `NOTICE.md`.

data/lib/facturx/attach.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'xml/verifier'
+require_relative 'pdf/inspector'
+require_relative 'pdf/extractor'
+require_relative 'pdf/verifier'
+require_relative 'composers/ghostscript'
+
+module Facturx
+  class Attach
+    def initialize(
+      xml_verifier: Xml::Verifier.new,
+      pdf_inspector: Pdf::Inspector.new,
+      composer: Composers::Ghostscript.new,
+      extractor: Pdf::Extractor.new,
+      pdf_verifier: Pdf::Verifier.new
+    )
+      @xml_verifier = xml_verifier
+      @pdf_inspector = pdf_inspector
+      @composer = composer
+      @extractor = extractor
+      @pdf_verifier = pdf_verifier
+    end
+
+    def call(pdf:, xml:)
+      profile = @xml_verifier.call(xml:)
+      inspection = @pdf_inspector.call(pdf)
+      output = @composer.call(pdf:, xml:, profile:)
+      result = @extractor.call(output)
+      @pdf_verifier.call(result:, expected_xml: xml, expected_page_count: inspection.page_count, profile:)
+      output
+    end
+  end
+end

data/lib/facturx/composers/ghostscript/defaults.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Facturx
+  module Composers
+    class Ghostscript
+      module Defaults
+        ENV_KEYS = {
+          binary: 'GHOSTSCRIPT_BIN',
+          zugferd_ps: 'FACTURX_ZUGFERD_PS',
+          icc_profile: 'FACTURX_ICC_PROFILE'
+        }.freeze
+        BINARY_NAMES = %w[gs gswin64c.exe gswin32c.exe].freeze
+        ZUGFERD_CANDIDATES = [
+          '/usr/share/ghostscript/*/lib/zugferd.ps',
+          '/usr/local/share/ghostscript/*/lib/zugferd.ps',
+          '/opt/homebrew/share/ghostscript/*/lib/zugferd.ps',
+          '/opt/local/share/ghostscript/*/lib/zugferd.ps'
+        ].freeze
+        ICC_CANDIDATES = [
+          '/usr/share/color/icc/ghostscript/default_rgb.icc',
+          '/usr/share/ghostscript/*/iccprofiles/default_rgb.icc',
+          '/usr/local/share/ghostscript/*/iccprofiles/default_rgb.icc',
+          '/opt/homebrew/share/ghostscript/*/iccprofiles/default_rgb.icc',
+          '/opt/local/share/ghostscript/*/iccprofiles/default_rgb.icc'
+        ].freeze
+      end
+    end
+  end
+end

data/lib/facturx/composers/ghostscript/locator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative 'defaults'
+require_relative 'version_probe'
+
+module Facturx
+  module Composers
+    class Ghostscript
+      class Locator
+        Config = Data.define(:binary, :zugferd_ps, :icc_profile)
+        ENV_KEYS = Defaults::ENV_KEYS
+
+        def initialize(
+          binary: nil,
+          zugferd_ps: nil,
+          icc_profile: nil,
+          version_probe: VersionProbe.new,
+          **discovery
+        )
+          @overrides = { binary:, zugferd_ps:, icc_profile: }
+          @env = discovery.fetch(:env, ENV)
+          candidates = discovery.fetch(:candidates, {})
+          @zugferd_candidates = candidates.fetch(:zugferd_ps, Defaults::ZUGFERD_CANDIDATES)
+          @icc_candidates = candidates.fetch(:icc_profile, Defaults::ICC_CANDIDATES)
+          @version_probe = version_probe
+        end
+
+        def available?
+          preflight!
+          true
+        rescue ComposerUnavailableError
+          false
+        end
+
+        def preflight!
+          candidate = config
+          missing_resources = missing(candidate)
+          raise_missing(missing_resources) unless missing_resources.empty?
+          verify_version!(candidate.binary)
+          @config = candidate
+        end
+
+        private
+
+        def config
+          @config || Config.new(
+            binary: resolve_binary,
+            zugferd_ps: resolve_resource(:zugferd_ps, @zugferd_candidates),
+            icc_profile: resolve_resource(:icc_profile, @icc_candidates)
+          )
+        end
+
+        def missing(candidate)
+          candidate.to_h.filter_map { |name, value| name if value.nil? }
+        end
+
+        def raise_missing(resources)
+          raise ComposerUnavailableError.new(
+            "Ghostscript composition is unavailable: missing #{resources.join(', ')}",
+            missing: resources
+          )
+        end
+
+        def verify_version!(binary)
+          @verify_version ||= @version_probe.call(binary)
+        end
+
+        def resolve_binary
+          configured = configured_value(:binary)
+          return find_executable(configured) if configured
+
+          Defaults::BINARY_NAMES.lazy.filter_map { |name| find_executable(name) }.first
+        end
+
+        def resolve_resource(name, candidates)
+          configured = configured_value(name)
+          return readable_file(configured) if configured
+
+          candidates.lazy.flat_map { |pattern| Dir.glob(pattern).reverse }.filter_map do |path|
+            readable_file(path)
+          end.first
+        end
+
+        def configured_value(name)
+          override = @overrides.fetch(name)
+          return override unless blank?(override)
+
+          value = @env[ENV_KEYS.fetch(name)]
+          value unless blank?(value)
+        end
+
+        def find_executable(value)
+          path = value.to_s
+          return executable_file(path) if path.include?(File::SEPARATOR) ||
+                                          (File::ALT_SEPARATOR && path.include?(File::ALT_SEPARATOR))
+
+          executable_extensions(path).each do |executable_name|
+            search_paths.each do |directory|
+              executable = executable_file(File.join(directory, executable_name))
+              return executable if executable
+            end
+          end
+
+          nil
+        end
+
+        def executable_extensions(name)
+          return [name] unless Gem.win_platform? && File.extname(name) == ''
+
+          extensions = @env.fetch('PATHEXT', '.COM;.EXE;.BAT;.CMD').split(';')
+          [name, *extensions.map { |extension| "#{name}#{extension.downcase}" }]
+        end
+
+        def search_paths
+          @env.fetch('PATH', '').split(File::PATH_SEPARATOR).reject(&:empty?)
+        end
+
+        def executable_file(path)
+          expanded = File.expand_path(path)
+          expanded if File.file?(expanded) && File.executable?(expanded)
+        end
+
+        def readable_file(path)
+          expanded = File.expand_path(path.to_s)
+          expanded if File.file?(expanded) && File.readable?(expanded)
+        end
+
+        def blank?(value)
+          value.nil? || value.to_s.empty?
+        end
+      end
+    end
+  end
+end

data/lib/facturx/composers/ghostscript/output_capture.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Facturx
+  module Composers
+    class Ghostscript
+      class OutputCapture
+        TRUNCATION_MARKER = '...[truncated]'
+
+        def initialize(stream, limit:)
+          @stream = stream
+          @limit = limit
+        end
+
+        def call
+          buffer = +''.b
+          truncated = false
+          while (chunk = @stream.read(4_096))
+            remaining = @limit - buffer.bytesize
+            buffer << chunk.byteslice(0, remaining) if remaining.positive?
+            truncated ||= chunk.bytesize > remaining
+          end
+          truncate(buffer, truncated)
+        rescue IOError
+          buffer
+        end
+
+        private
+
+        def truncate(buffer, truncated)
+          return buffer unless truncated
+
+          marker = TRUNCATION_MARKER.byteslice(0, @limit)
+          kept_bytes = [@limit - marker.bytesize, 0].max
+          buffer.byteslice(0, kept_bytes).to_s << marker
+        end
+      end
+    end
+  end
+end

data/lib/facturx/composers/ghostscript/runner.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+require_relative '../../error'
+require_relative 'output_capture'
+
+module Facturx
+  module Composers
+    class Ghostscript
+      class Runner
+        Result = Data.define(:stdout, :stderr, :exit_status)
+
+        DEFAULT_TIMEOUT = 60
+        DEFAULT_OUTPUT_LIMIT = 8_192
+        DEFAULT_TERMINATION_GRACE = 1
+        def initialize(
+          timeout: DEFAULT_TIMEOUT,
+          output_limit: DEFAULT_OUTPUT_LIMIT,
+          termination_grace: DEFAULT_TERMINATION_GRACE
+        )
+          @timeout = timeout
+          @output_limit = output_limit
+          @termination_grace = termination_grace
+        end
+
+        def call(argv)
+          result = execute(argv)
+          return result if result.exit_status.zero?
+
+          raise_failed(result)
+        rescue CompositionError
+          raise
+        rescue SystemCallError => e
+          raise CompositionError.new(
+            "Ghostscript could not be executed: #{e.message}",
+            cause: e.class.name
+          )
+        end
+
+        private
+
+        def execute(argv)
+          Open3.popen3(*argv, pgroup: true) do |stdin, stdout, stderr, wait_thread|
+            capture_process(stdin, stdout, stderr, wait_thread)
+          end
+        end
+
+        def capture_process(stdin, stdout, stderr, wait_thread)
+          stdin.close
+          stdout_reader = capture(stdout)
+          stderr_reader = capture(stderr)
+          build_result(wait_thread, stdout_reader, stderr_reader)
+        ensure
+          stdout_reader&.join
+          stderr_reader&.join
+        end
+
+        def build_result(wait_thread, stdout_reader, stderr_reader)
+          status = wait_for(wait_thread, stderr_reader)
+          Result.new(
+            stdout: stdout_reader.value,
+            stderr: stderr_reader.value,
+            exit_status: exit_status(status)
+          )
+        end
+
+        def exit_status(status)
+          status.exitstatus || (128 + status.termsig)
+        end
+
+        def raise_failed(result)
+          raise CompositionError.new(
+            "Ghostscript failed with exit status #{result.exit_status}",
+            exit_status: result.exit_status,
+            stdout: sanitize(result.stdout),
+            stderr: sanitize(result.stderr)
+          )
+        end
+
+        def wait_for(wait_thread, stderr_reader)
+          Timeout.timeout(@timeout) { wait_thread.value }
+        rescue Timeout::Error
+          terminate(wait_thread)
+          raise CompositionError.new(
+            "Ghostscript timed out after #{@timeout} seconds",
+            timeout: @timeout,
+            stderr: sanitize(stderr_reader.value)
+          )
+        end
+
+        def capture(stream)
+          Thread.new { OutputCapture.new(stream, limit: @output_limit).call }
+        end
+
+        def terminate(wait_thread)
+          signal('TERM', wait_thread.pid)
+          return if wait_thread.join(@termination_grace)
+
+          signal('KILL', wait_thread.pid)
+          wait_thread.join
+        end
+
+        def signal(name, pid)
+          Process.kill(name, -pid)
+        rescue Errno::ESRCH
+          nil
+        rescue SystemCallError
+          begin
+            Process.kill(name, pid)
+          rescue Errno::ESRCH
+            nil
+          end
+        end
+
+        def sanitize(output)
+          output.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '?').strip
+        end
+      end
+    end
+  end
+end

data/lib/facturx/composers/ghostscript/version_probe.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'rubygems/version'
+require_relative 'runner'
+
+module Facturx
+  module Composers
+    class Ghostscript
+      class VersionProbe
+        MINIMUM_VERSION = Gem::Version.new('9.54')
+        VERSION_PATTERN = /\A\d+(?:\.\d+)+\z/
+
+        def initialize(runner: Runner.new)
+          @runner = runner
+        end
+
+        def call(binary)
+          validate(parse(@runner.call([binary, '--version']).stdout))
+        rescue CompositionError => e
+          raise_probe_failure(e)
+        end
+
+        private
+
+        def parse(output)
+          value = output.to_s.lines.first.to_s.strip
+          raise_missing_version if value.empty?
+          raise_invalid_version unless VERSION_PATTERN.match?(value)
+          Gem::Version.new(value)
+        end
+
+        def validate(version)
+          return version if version >= MINIMUM_VERSION
+
+          raise ComposerUnavailableError.new(
+            "Ghostscript #{version} is unsupported; version #{MINIMUM_VERSION} or newer is required",
+            reason: :unsupported_version,
+            detected_version: version.to_s,
+            minimum_version: MINIMUM_VERSION.to_s
+          )
+        end
+
+        def raise_missing_version
+          raise ComposerUnavailableError.new('Ghostscript did not report its version', reason: :missing_version)
+        end
+
+        def raise_invalid_version
+          raise ComposerUnavailableError.new('Ghostscript reported an invalid version', reason: :invalid_version)
+        end
+
+        def raise_probe_failure(error)
+          raise ComposerUnavailableError.new(
+            'Unable to determine the Ghostscript version',
+            reason: :version_unavailable,
+            probe_error: error.details
+          )
+        end
+      end
+    end
+  end
+end

data/lib/facturx/composers/ghostscript.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require_relative '../embedding'
+require_relative 'ghostscript/locator'
+require_relative 'ghostscript/runner'
+
+module Facturx
+  module Composers
+    class Ghostscript
+      INPUT_FILENAME = 'input.pdf'
+      OUTPUT_FILENAME = 'output.pdf'
+      DEVICE_ARGUMENTS = %w[
+        -dBATCH
+        -dNOPAUSE
+        -sDEVICE=pdfwrite
+        -dPDFA=3
+        -dPDFACompatibilityPolicy=1
+        -sColorConversionStrategy=RGB
+      ].freeze
+
+      Paths = Data.define(:input, :xml, :output)
+
+      def initialize(locator: Locator.new, runner: Runner.new)
+        @locator = locator
+        @runner = runner
+      end
+
+      def available?
+        @locator.available?
+      end
+
+      def preflight!
+        @locator.preflight!
+      end
+
+      def call(pdf:, xml:, profile:)
+        config = preflight!
+        Dir.mktmpdir('facturx-') do |directory|
+          paths = paths_for(directory)
+          write_inputs(paths, pdf, xml)
+          @runner.call(arguments(config, paths, profile))
+          read_output(paths.output)
+        end
+      rescue SystemCallError => e
+        raise_temporary_file_error(e)
+      end
+
+      private
+
+      def raise_temporary_file_error(error)
+        raise CompositionError.new(
+          "Ghostscript composition failed while handling temporary files: #{error.message}",
+          cause: error.class.name
+        )
+      end
+
+      def paths_for(directory)
+        Paths.new(
+          input: File.join(directory, INPUT_FILENAME),
+          xml: File.join(directory, FACTURX_EMBEDDING.filename),
+          output: File.join(directory, OUTPUT_FILENAME)
+        )
+      end
+
+      def write_inputs(paths, pdf, xml)
+        File.binwrite(paths.input, pdf)
+        File.binwrite(paths.xml, xml)
+      end
+
+      def arguments(config, paths, profile)
+        [config.binary, permitted_files_argument(config, paths)] + DEVICE_ARGUMENTS +
+          zugferd_arguments(config, paths, profile) + ['-o', paths.output, config.zugferd_ps, paths.input]
+      end
+
+      def permitted_files_argument(config, paths)
+        permitted_files = [
+          paths.input,
+          paths.xml,
+          config.zugferd_ps,
+          config.icc_profile
+        ].join(File::PATH_SEPARATOR)
+
+        "--permit-file-read=#{permitted_files}"
+      end
+
+      def zugferd_arguments(config, paths, profile)
+        [
+          "-sZUGFeRDXMLFile=#{paths.xml}",
+          "-sZUGFeRDProfile=#{config.icc_profile}",
+          '-sZUGFeRDVersion=2p1',
+          "-sZUGFeRDConformanceLevel=#{profile.conformance_level}"
+        ]
+      end
+
+      def read_output(path)
+        unless File.file?(path) && File.size?(path)
+          raise CompositionError, 'Ghostscript did not produce a non-empty PDF'
+        end
+
+        File.binread(path)
+      end
+    end
+  end
+end

data/lib/facturx/embedding.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Facturx
+  Embedding = Data.define(:filename, :relationship, :document_type, :version, :xmp_namespace)
+
+  FACTURX_EMBEDDING = Embedding.new(
+    filename: 'factur-x.xml',
+    relationship: :Alternative,
+    document_type: 'INVOICE',
+    version: '1.0',
+    xmp_namespace: 'urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#'
+  )
+
+  private_constant :Embedding, :FACTURX_EMBEDDING
+end