swiss_qr 0.1.0

data/lib/swiss_qr/parser.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module SwissQr
+  # Turns a Swiss QR Code payload into a Bill. Use SwissQr.parse.
+  class Parser
+    include Validation
+
+    BOM = "\uFEFF"
+    # Encodings that QR decoders commonly (and wrongly, for coding type 1)
+    # tag byte-mode segments with; valid UTF-8 bytes in them are UTF-8.
+    MISTAGGED_ENCODINGS = [Encoding::ISO_8859_1, Encoding::Windows_1252].freeze
+    # Header lines as parse recognizes them (blanks around SPC and the
+    # version are tolerated here so that looks_like_qr_bill? never skips what parse
+    # would report as an invalid QR-bill).
+    HEADER = /\A(?:\xEF\xBB\xBF)?[ \t]*SPC[ \t]*\r?\n[ \t]*\d{4}[ \t]*\r?\n/n
+
+    def self.parse(payload, strict: true)
+      new(payload).parse(strict: strict)
+    end
+
+    # Cheap check whether +text+ looks like a QR-bill payload ("SPC", a
+    # line break, a four-digit version and another line break).
+    def self.looks_like_qr_bill?(text)
+      return false unless text.respond_to?(:to_str)
+
+      text = text.to_str
+      text.b.match?(HEADER) || (!text.encoding.ascii_compatible? && utf8_bytes(text).match?(HEADER))
+    end
+
+    # The UTF-8 bytes of a UTF-16/UTF-32 string, for the byte-level match.
+    def self.utf8_bytes(text)
+      text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace).b
+    rescue EncodingError
+      text.b
+    end
+    private_class_method :utf8_bytes
+
+    def initialize(payload)
+      raise TypeError, "payload must be a String (got #{payload.class})" unless payload.respond_to?(:to_str)
+
+      @payload = payload.to_str
+      @errors = []
+      @warnings = []
+    end
+
+    def parse(strict: true)
+      text = utf8(@payload)
+      @raw = text.frozen? ? text : text.dup.freeze
+      check_input_size!(text)
+      text = strip_bom(text)
+      lines = split_lines(text)
+      check_structure!(lines)
+      values = read_values(lines)
+      bill = build_bill(values)
+      raise InvalidPayload.new(bill.errors, bill: bill) if strict && !bill.valid?
+
+      bill
+    end
+
+    private
+
+    def utf8(text)
+      return text if text.encoding == Encoding::UTF_8 && text.valid_encoding?
+
+      text = text.dup
+      if [Encoding::BINARY, Encoding::US_ASCII, Encoding::UTF_8].include?(text.encoding)
+        text.force_encoding(Encoding::UTF_8)
+      elsif mistagged_utf8?(text)
+        warning(:payload, "payload tagged #{text.encoding} is valid UTF-8 and was read as UTF-8 (coding type 1)")
+        text.force_encoding(Encoding::UTF_8)
+      else
+        begin
+          text = text.encode(Encoding::UTF_8)
+        rescue EncodingError
+          text.force_encoding(Encoding::UTF_8)
+        end
+      end
+      return text if text.valid_encoding?
+
+      error(:payload, "payload is not valid UTF-8")
+      text.scrub("\uFFFD")
+    end
+
+    # QR byte segments without an ECI are ISO-8859-1 by default, so many
+    # decoders tag a QR-bill's UTF-8 bytes that way; transcoding them would
+    # turn "ö" into "ö".
+    def mistagged_utf8?(text)
+      MISTAGGED_ENCODINGS.include?(text.encoding) && !text.ascii_only? &&
+        text.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+    end
+
+    def strip_bom(text)
+      return text unless text.start_with?(BOM)
+
+      warning(:payload, "byte order mark (BOM) removed")
+      text.delete_prefix(BOM)
+    end
+
+    # Drops the final line break and trailing empty (or blank) lines that
+    # many generators (SIX's own samples included) leave behind, then splits
+    # on CR LF or LF and checks the separators between the remaining lines.
+    def split_lines(text)
+      body = text.sub(/(?:\r\n|\n|\r)\s*\z/, "")
+      @crlf = body.include?("\r\n")
+      if @crlf && body.match?(/(?<!\r)\n/)
+        error(:payload, "CR LF and LF line separators are mixed; IG 4.1.4 requires the same separator throughout")
+      end
+      error(:payload, "a lone CR is not a permitted line separator (use CR LF or LF)") if body.match?(/\r(?!\n)/)
+
+      body.split(/\r?\n/, -1)
+    end
+
+    def check_structure!(lines)
+      header = lines.first&.strip
+      if header != QR_TYPE
+        message = header.nil? ? "empty payload" : %(QR type must be "#{QR_TYPE}" (got #{header[0, 20].inspect}))
+        raise InvalidPayload, @errors + [Problem.new(field: :header, message: message)]
+      end
+      return if lines.size >= MIN_LINES
+
+      message = "only #{lines.size} lines (not counting trailing empty lines); " \
+                "a QR-bill has #{MIN_LINES} to #{MAX_LINES} lines ending with the trailer #{TRAILER.inspect}"
+      raise InvalidPayload, @errors + [Problem.new(field: :payload, message: message)]
+    end
+
+    # Checks character set, padding and overall size; returns the stripped
+    # line values with empty lines as nil. Lines beyond MAX_LINES are
+    # reported by check_size and otherwise ignored.
+    def read_values(lines)
+      check_size(lines)
+      lines = lines.first(MAX_LINES)
+      fields = line_fields(lines)
+      lines.each_with_index.map do |line, index|
+        field = fields.fetch(index, :payload)
+        status_a = index >= MIN_LINES
+        check_characters(field, line, status_a: status_a)
+        value = line.strip
+        check_padding(field, line, value, status_a: status_a) if value != line
+        value.empty? ? nil : value.freeze
+      end
+    end
+
+    def check_size(lines)
+      if lines.size > MAX_LINES
+        error(:payload, "#{lines.size} lines; at most #{MAX_LINES} are permitted (31 + billing information + " \
+                        "2 alternative procedures), the extra lines are ignored")
+      end
+      length = lines.sum(&:length) + lines.size - 1 # separators count as one character each (LF)
+      length += lines.size - 1 if @crlf
+      return if length <= MAX_PAYLOAD_LENGTH
+
+      error(:payload, "payload is #{length} characters including separators; at most #{MAX_PAYLOAD_LENGTH} are permitted")
+    end
+
+    def line_fields(lines)
+      %i[header version coding_type iban] +
+        address_fields(:creditor, lines[4]&.strip) +
+        address_fields(:ultimate_creditor, lines[11]&.strip) +
+        %i[amount currency] +
+        address_fields(:debtor, lines[20]&.strip) +
+        %i[reference_type reference unstructured_message trailer billing_information
+           alternative_procedures alternative_procedures]
+    end
+
+    # Fields are validated in line order so that errors come out in that order.
+    def build_bill(values)
+      check_header(values[1], values[2])
+      attributes = { version: values[1], coding_type: values[2] }
+      attributes.merge!(parties_and_amount(values))
+      attributes.merge!(reference_attributes(values, attributes))
+      attributes.merge!(additional_information(values, attributes[:amount]))
+      Bill.new(**attributes, errors: @errors.dup.freeze, warnings: @warnings.dup.freeze, raw: @raw)
+    end
+
+    def parties_and_amount(values)
+      iban = values[3] && Iban.normalize(values[3]).freeze
+      check_iban(values[3], iban)
+      {
+        iban: iban,
+        qr_iban: !iban.nil? && Iban.qr_iid?(iban),
+        creditor: build_address(:creditor, values[4, 7], required: true),
+        ultimate_creditor: build_ultimate_creditor(values[11, 7]),
+        amount: parse_amount(values[18]),
+        currency: values[19].tap { |currency| check_currency(currency) },
+        debtor: build_address(:debtor, values[20, 7], required: false)
+      }
+    end
+
+    def reference_attributes(values, attributes)
+      reference_type = parse_reference_type(values[27])
+      check_iban_reference_type(attributes[:iban], attributes[:qr_iban], reference_type, attributes[:currency])
+      check_reference(reference_type, values[28])
+      { reference_type: reference_type, reference: values[28] }
+    end
+
+    def additional_information(values, amount)
+      message, trailer, raw_billing_information = values[29, 3]
+      alternative_procedures = values[32, 2] || []
+      check_notification(amount, message)
+      check_trailer(trailer)
+      check_additional_information(message, raw_billing_information)
+      billing_information = parse_billing_information(raw_billing_information)
+      check_alternative_procedures(alternative_procedures)
+      {
+        unstructured_message: message, trailer: trailer, raw_billing_information: raw_billing_information,
+        billing_information: billing_information,
+        alternative_procedures: alternative_procedures.compact.freeze
+      }
+    end
+  end
+end

data/lib/swiss_qr/reader.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+# QR code readers and SwissQr.read / SwissQr.read_all.
+module SwissQr
+  # Pluggable QR code readers: turn an image or PDF into the texts of the QR
+  # codes on it. SwissQr.read and SwissQr.read_all use SwissQr.reader, which
+  # defaults to the +qr_reader+ gem; any other decoder can be plugged in.
+  #
+  # A reader is either
+  # - an object responding to <tt>decode_all(input)</tt> and returning an
+  #   Array of Strings (the +QrReader+ module itself qualifies), or
+  # - a callable (Proc, Method, any object with #call) returning a String,
+  #   an Array of Strings, or nil when nothing was found.
+  #
+  # Elements may also be result objects with a #text method (such as
+  # QrReader::Result); nil elements are dropped.
+  #
+  # The input handed to a reader is never image bytes in a String: a String
+  # is a file path (image bytes come as an IO such as StringIO.new(bytes)).
+  module Reader
+    # Leading bytes of the image formats a String of image bytes most likely
+    # has; together with NUL bytes (never in a path) they reveal image data
+    # passed where a path belongs.
+    IMAGE_MAGIC = ["\x89PNG".b, "\xFF\xD8\xFF".b, "GIF8".b, "%PDF-".b, "II*\0".b, "MM\0*".b,
+                   "\0\0\0\x0CjP".b, "\xFF\x4F\xFF\x51".b].freeze
+
+    INSTALL_HINT = <<~HINT.tr("\n", " ").strip
+      Reading QR codes from images and PDFs needs the qr_reader gem: run
+      "gem install qr_reader" or "bundle add qr_reader", or plug in another
+      decoder with SwissQr.reader = ->(input) { ... } (or pass reader: to
+      SwissQr.read).
+    HINT
+
+    # The default reader: the +qr_reader+ gem, required on first use (not
+    # when swiss_qr is loaded). Raises ReaderUnavailable when it cannot be
+    # loaded; the next call tries again.
+    #
+    # +options+ are passed on to qr_reader (<tt>try_harder:</tt>,
+    # <tt>inverted:</tt>):
+    #
+    #   SwissQr.reader = SwissQr::Reader::QrReaderAdapter.new(try_harder: false)
+    class QrReaderAdapter
+      # The oldest qr_reader this adapter works with. Older releases sniff
+      # Strings (image bytes or path), raise for PDFs without any code, and
+      # crash ruby.wasm on PNGs.
+      MINIMUM_QR_READER = "0.0.3"
+
+      attr_reader :options
+
+      def initialize(**options)
+        @options = options.freeze
+      end
+
+      def decode_all(input)
+        reader = qr_reader
+        reader.decode_all(input, **options)
+      end
+
+      # Yields the text of each code as soon as it is decoded, so that
+      # SwissQr.read can stop at the first QR-bill of a long PDF.
+      def each_text(input, &)
+        reader = qr_reader
+        reader.scan(input, **options) { |result| yield result.text }
+      end
+
+      def inspect
+        shown = options.empty? ? "" : " #{options.inspect}"
+        "#<#{self.class.name}#{shown} (qr_reader gem, loaded on first use)>"
+      end
+
+      private
+
+      def qr_reader
+        begin
+          require "qr_reader"
+        rescue LoadError => e
+          raise ReaderUnavailable, "#{INSTALL_HINT} (#{e.message})"
+        end
+        check_version(::QrReader::VERSION)
+        ::QrReader
+      end
+
+      # Compared without Gem::Version, so that this also works where
+      # RubyGems is not loaded (ruby.wasm, --disable-gems).
+      def check_version(version)
+        numbers = ->(v) { v.to_s.split(".").map(&:to_i) }
+        return if (numbers.call(version) <=> numbers.call(MINIMUM_QR_READER)) >= 0
+
+        raise ReaderUnavailable, "qr_reader #{version} is too old: swiss_qr needs qr_reader " \
+                                 "#{MINIMUM_QR_READER} or newer (gem update qr_reader / bundle update qr_reader)"
+      end
+    end
+
+    # Wraps any supported reader in an object answering #decode_all and
+    # #each_text with plain Strings.
+    class Adapter
+      attr_reader :reader
+
+      def initialize(reader)
+        @reader = reader
+      end
+
+      def decode_all(input)
+        texts = []
+        each_text(input) { |text| texts << text }
+        texts
+      end
+
+      def each_text(input, &)
+        return reader.each_text(input, &) if reader.is_a?(QrReaderAdapter)
+
+        result = reader.respond_to?(:decode_all) ? reader.decode_all(input) : reader.call(input)
+        Reader.texts(result).each(&)
+      end
+    end
+
+    module_function
+
+    # Refuses image bytes passed as a String, where a path belongs: a String
+    # input is always a file path. Without this, bytes from a client that
+    # spell a path on the server would be read from disk.
+    def check_input(input)
+      return input unless input.is_a?(String)
+
+      bytes = input.b
+      return input if !bytes.include?("\0") && File.file?(input)
+      if bytes.include?("\0") || IMAGE_MAGIC.any? { |magic| bytes.start_with?(magic) }
+        raise ArgumentError, "expected a file path, got a String that looks like image data " \
+                             "(#{bytes.bytesize} bytes); pass image bytes as an IO: StringIO.new(bytes)"
+      end
+
+      input
+    end
+
+    # True when +reader+ can be used as a reader.
+    def reader?(reader)
+      reader.respond_to?(:decode_all) || reader.respond_to?(:call)
+    end
+
+    # Wraps +reader+ (see Reader) in an Adapter; nil means SwissQr.reader.
+    def adapt(reader)
+      reader = SwissQr.reader if reader.nil?
+      return reader if reader.is_a?(Adapter)
+      raise ArgumentError, "a reader must respond to #decode_all or #call (got #{reader.inspect})" unless reader?(reader)
+
+      Adapter.new(reader)
+    end
+
+    # Normalises what a reader returned into an Array of Strings. A single
+    # String or result object (with #text) counts as one code; it is not
+    # splatted with Array() (a Struct result would turn into its fields).
+    def texts(result)
+      items = result.respond_to?(:to_str) || result.respond_to?(:text) ? [result] : Array(result)
+      items.filter_map { |item| text(item) }
+    end
+
+    def text(item)
+      return if item.nil?
+      return item.to_str if item.respond_to?(:to_str)
+      return item.text&.to_s if item.respond_to?(:text)
+
+      raise TypeError, "a reader must return Strings (or objects with #text), got #{item.class}"
+    end
+  end
+
+  @reader = nil
+  @reader_lock = Mutex.new
+
+  class << self
+    # The reader used by read and read_all: what was assigned with reader=,
+    # or else a Reader::QrReaderAdapter for the +qr_reader+ gem (which is
+    # only required when a code is actually read).
+    def reader
+      @reader || @reader_lock.synchronize { @reader ||= Reader::QrReaderAdapter.new }
+    end
+
+    # Replaces the reader for the whole process: an object with
+    # <tt>decode_all(input)</tt> or a callable (see Reader). +nil+ restores
+    # the default (+qr_reader+).
+    #
+    #   SwissQr.reader = ->(path) { `zbarimg --quiet --raw #{path}`.split("\n") }
+    def reader=(reader)
+      unless reader.nil? || Reader.reader?(reader)
+        raise ArgumentError, "a reader must respond to #decode_all or #call (got #{reader.inspect})"
+      end
+
+      @reader_lock.synchronize { @reader = reader }
+    end
+
+    # Reads the QR codes in +input+ - a file path (String or Pathname), an
+    # IO with the image or PDF (StringIO.new(bytes), an upload's Tempfile),
+    # or whatever else the reader accepts, such as a ChunkyPNG image - and
+    # returns the first QR-bill as a Bill, or nil when there is none. A
+    # String is always a path: image bytes in a String raise ArgumentError.
+    # Codes that are not QR-bills (see looks_like_qr_bill?) are skipped. +strict+ is
+    # passed on to parse.
+    def read(input, reader: self.reader, strict: true)
+      Reader.adapt(reader).each_text(Reader.check_input(input)) do |text|
+        return parse(text, strict: strict) if looks_like_qr_bill?(text)
+      end
+      nil
+    end
+
+    # Like read, but returns every QR-bill found (all pages), in the order
+    # the reader reported them; an empty Array when there is none.
+    def read_all(input, reader: self.reader, strict: true)
+      texts = Reader.adapt(reader).decode_all(Reader.check_input(input))
+      texts.select { |text| looks_like_qr_bill?(text) }.map { |text| parse(text, strict: strict) }
+    end
+  end
+end

data/lib/swiss_qr/reference.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SwissQr
+  # Payment reference helpers: the 27-digit QR reference (QRR, used with a
+  # QR-IBAN) and the ISO 11649 creditor reference (SCOR, "RF..." with an
+  # ordinary IBAN).
+  #
+  # All predicates ignore whitespace, so display-formatted references are
+  # accepted. The parser itself is stricter and rejects spaces in a payload.
+  module Reference
+    QRR_PATTERN = /\A\d{27}\z/
+    SCOR_PATTERN = /\ARF\d{2}[A-Z0-9]{1,21}\z/
+
+    module_function
+
+    def normalize(reference)
+      reference.to_s.gsub(/[[:space:]]/, "")
+    end
+
+    # True for 27 digits with a correct modulo-10 recursive check digit that
+    # are not all zeros (IG 2.3).
+    def valid_qrr?(reference)
+      value = normalize(reference)
+      value.match?(QRR_PATTERN) && !value.match?(/\A0+\z/) &&
+        Checksum.mod10_recursive(value[0, 26]) == value[26].to_i
+    end
+
+    # True for a 5-25 character creditor reference "RF" + 2 check digits +
+    # up to 21 alphanumerics with valid MOD 97-10 check digits. Case-insensitive.
+    def valid_scor?(reference)
+      value = normalize(reference).upcase
+      value.match?(SCOR_PATTERN) && Checksum.mod97(value) == 1
+    end
+
+    # Appends the check digit to up to 26 digits (left-padded with zeros):
+    # <tt>build_qrr("21000000000313947143000901")</tt> => "210000000003139471430009017".
+    def build_qrr(digits)
+      body = normalize(digits)
+      raise ArgumentError, "QR reference body must be 1-26 digits" unless body.match?(/\A\d{1,26}\z/)
+
+      body = body.rjust(26, "0")
+      "#{body}#{Checksum.mod10_recursive(body)}"
+    end
+
+    # Builds a creditor reference from up to 21 alphanumerics:
+    # <tt>build_scor("539007547034")</tt> => "RF18539007547034".
+    def build_scor(payload)
+      body = normalize(payload).upcase
+      raise ArgumentError, "creditor reference body must be 1-21 alphanumerics" unless body.match?(/\A[A-Z0-9]{1,21}\z/)
+
+      check = 98 - Checksum.mod97("RF00#{body}")
+      Kernel.format("RF%<check>02d%<body>s", check: check, body: body)
+    end
+
+    # Display form of a QR reference: "21 00000 00003 13947 14300 09017"
+    # (groups of five from the right).
+    def format_qrr(reference)
+      value = normalize(reference)
+      value.reverse.scan(/.{1,5}/).join(" ").reverse
+    end
+
+    # Display form of a creditor reference: "RF18 5390 0754 7034".
+    def format_scor(reference)
+      normalize(reference).upcase.scan(/.{1,4}/).join(" ")
+    end
+
+    # Display form chosen by shape (QRR if all digits, otherwise SCOR style).
+    def format(reference, type = nil)
+      return nil if reference.nil?
+
+      type ||= normalize(reference).match?(/\A\d+\z/) ? :qrr : :scor
+      case type
+      when :qrr then format_qrr(reference)
+      when :scor then format_scor(reference)
+      else reference.to_s
+      end
+    end
+  end
+end