zatca-sdk 1.1.0

data/lib/zatca/signing/csr.rb

@@ -0,0 +1,220 @@
+class ZATCA::Signing::CSR
+  attr_reader :key, :csr_options, :mode
+
+  # For security purposes, please provide your own private key.
+  # If you don't provide one, a new unsecure one will be generated for testing purposes.
+  def initialize(
+    csr_options:,
+    mode: :production,
+    private_key_path: nil,
+    private_key_password: nil
+  )
+    @csr_options = default_csr_options.merge(csr_options)
+    @mode = mode.to_sym
+    @private_key_path = private_key_path
+    @private_key_password = private_key_password
+    @generated_private_key_path = nil
+  end
+
+  # Returns a hash with two keys
+  # - csr
+  # - csr_without_headers
+  def generate(csr_options: {})
+    set_key
+    write_csr_config
+
+    command = generate_openssl_csr_command
+
+    # Run the command and return the output
+    output = `#{command}`
+
+    cleanup_leftover_files
+
+    output
+
+    # TODO: Ruby version
+    # request = OpenSSL::X509::Request.new
+    # request.version = 0
+    # request.subject = OpenSSL::X509::Name.new([
+    #   ["C", csr_options[:country], OpenSSL::ASN1::PRINTABLESTRING],
+    #   ["O", csr_options[:organization], OpenSSL::ASN1::UTF8STRING],
+    #   ["OU", csr_options[:organization_unit], OpenSSL::ASN1::UTF8STRING],
+    #   ["CN", csr_options[:common_name], OpenSSL::ASN1::UTF8STRING]
+    # ])
+
+    # extensions = [
+    #   OpenSSL::X509::ExtensionFactory.new.create_extension("subjectAltName")
+    # ]
+
+    # # add SAN extension to the CSR
+    # attribute_values = OpenSSL::ASN1::Set [OpenSSL::ASN1::Sequence(extensions)]
+    # [
+    #   OpenSSL::X509::Attribute.new("SN", attribute_values),
+    #   OpenSSL::X509::Attribute.new("UID", attribute_values),
+    #   OpenSSL::X509::Attribute.new("title", attribute_values),
+    #   OpenSSL::X509::Attribute.new("registeredAddress", attribute_values),
+    #   OpenSSL::X509::Attribute.new("businessCategory", attribute_values)
+    # ]
+
+    # attribute_values.each do |attribute|
+    #   request.add_attribute attribute
+    # end
+
+    # request.public_key = public_key
+    # csr = request.sign(key, OpenSSL::Digest.new("SHA256"))
+    # csr_pem = csr.to_pem
+    # csr_without_headers = csr_pem
+    #   .to_s
+    #   .gsub("-----BEGIN CERTIFICATE REQUEST-----", "")
+    #   .gsub("-----END CERTIFICATE REQUEST-----", "")
+    #   .delete("\n")
+
+    # {
+    #   csr: csr_pem,
+    #   csr_without_headers: csr_without_headers
+    # }
+  end
+
+  private
+
+  def default_csr_options
+    {
+      common_name: "",
+      organization_identifier: "",
+      organization_name: "",
+      organization_unit: "",
+      country: "SA",
+      invoice_type: "1100",
+      address: "",
+      business_category: "",
+      egs_solution_name: "",
+      egs_model: "",
+      egs_serial_number: ""
+    }
+  end
+
+  def set_key
+    if private_key_provided? && @key.blank?
+      @key = OpenSSL::PKey::EC.new(
+        File.read(@private_key_path),
+        @private_key_password
+      )
+    else
+      generate_key
+    end
+  end
+
+  def generated_key?
+    @key.present?
+  end
+
+  def private_key_provided?
+    @private_key_path.present?
+  end
+
+  def generate_key
+    return if private_key_provided?
+
+    temp_key = OpenSSL::PKey::EC.new("secp256k1").generate_key
+    @generated_private_key_path = "./#{SecureRandom.uuid}.pem"
+    @key = temp_key
+
+    File.write(@generated_private_key_path, @key.to_pem)
+  end
+
+  def delete_generated_key
+    File.delete(@generated_private_key_path) if @generated_private_key_path.present?
+  end
+
+  def cert_environment
+    case mode
+    when :production
+      "ZATCA-Code-Signing"
+    when :simulation
+      "PREZATCA-Code-Signing"
+    when :sandbox
+      "TSTZATCA-Code-Signing"
+    end
+  end
+
+  def generate_openssl_csr_command
+    "openssl req -new -sha256 -key #{@private_key_path || @generated_private_key_path} -config #{@csr_config_path}"
+  end
+
+  def write_csr_config
+    @csr_config_path = "./#{SecureRandom.uuid}.conf"
+    File.write(@csr_config_path, generate_csr_config)
+  end
+
+  def cleanup_leftover_files
+    delete_generated_key
+    delete_csr_config_file
+  end
+
+  def delete_csr_config_file
+    File.delete(@csr_config_path) if @csr_config_path.present?
+  end
+
+  def egs_serial_number
+    "1-#{csr_options[:egs_solution_name]}|2-#{csr_options[:egs_model]}|3-#{csr_options[:egs_serial_number]}"
+  end
+
+  # Adapted from:
+  # https://github.com/wes4m/zatca-xml-js/blob/main/src/zatca/templates/csr_template.ts
+  def generate_csr_config
+    <<~TEMPLATE
+      # ------------------------------------------------------------------
+      # Default section for "req" command csr_options
+      # ------------------------------------------------------------------
+      [req]
+
+      # Password for reading in existing private key file
+      # input_password = todo_private_key_password
+
+      # Prompt for DN field values and CSR attributes in ASCII
+      prompt = no
+      utf8 = no
+
+      # Section pointer for DN field csr_options
+      distinguished_name = my_req_dn_prompt
+
+      # Extensions
+      req_extensions = v3_req
+
+      [ v3_req ]
+      #basicConstraints=CA:FALSE
+      #keyUsage = digitalSignature, keyEncipherment
+      # Production or Testing Template (TSTZATCA-Code-Signing - ZATCA-Code-Signing)
+      1.3.6.1.4.1.311.20.2 = ASN1:PRINTABLESTRING:#{cert_environment}
+      subjectAltName=dirName:dir_sect
+
+      [ dir_sect ]
+      # EGS Serial number (1-SolutionName|2-ModelOrVersion|3-serialNumber)
+      SN = #{egs_serial_number}
+      # VAT Registration number of TaxPayer (Organization identifier [15 digits begins with 3 and ends with 3])
+      UID = #{csr_options[:organization_identifier]}
+      # Invoice type (TSCZ)(1 = supported, 0 not supported) (Tax, Simplified, future use, future use)
+      title = #{csr_options[:invoice_type]}
+      # Location (branch address or website)
+      registeredAddress = #{csr_options[:address]}
+      # Industry (industry sector name)
+      businessCategory = #{csr_options[:business_category]}
+
+      # ------------------------------------------------------------------
+      # Section for prompting DN field values to create "subject"
+      # ------------------------------------------------------------------
+      [my_req_dn_prompt]
+      # Common name (EGS TaxPayer PROVIDED ID [FREE TEXT])
+      commonName = #{csr_options[:common_name]}
+
+      # Organization Unit (Branch name)
+      organizationalUnitName = #{csr_options[:organization_unit]}
+
+      # Organization name (Tax payer name)
+      organizationName = #{csr_options[:organization_name]}
+
+      # ISO2 country code is required with US as default
+      countryName = #{csr_options[:country]}
+    TEMPLATE
+  end
+end

data/lib/zatca/signing/ecdsa.rb

@@ -0,0 +1,59 @@
+require "starkbank-ecdsa"
+
+class ZATCA::Signing::ECDSA
+  def self.sign(content:, private_key: nil, private_key_path: nil, decode_from_base64: false)
+    private_key = parse_private_key(key: private_key, key_path: private_key_path, decode_from_base64: decode_from_base64)
+
+    ecdsa_signature = EllipticCurve::Ecdsa.sign(content, private_key)
+
+    {
+      base64: ecdsa_signature.toBase64,
+      bytes: ecdsa_signature.toDer
+    }
+  end
+
+  def self.add_header_blocks(key_content)
+    # If key is missing header blocks, add them, otherwise return it as is
+    header = "-----BEGIN EC PRIVATE KEY-----"
+    footer = "-----END EC PRIVATE KEY-----"
+
+    unless key_content.include?(header) && key_content.include?(footer)
+      key_content = "#{header}\n#{key_content}\n#{footer}"
+    end
+
+    key_content
+  end
+
+  def self.read_private_key_from_pem(pem)
+    EllipticCurve::PrivateKey.fromPem(add_header_blocks(pem))
+  end
+
+  # Returns a parsed private key
+  # If decode_from_base64 is set to true, the key will be decoded from base64
+  # before passing to OpenSSL to read it. # This is necessary because that's how
+  # ZATCA's sample key is provided.
+  def self.parse_private_key(key: nil, key_path: nil, decode_from_base64: false)
+    parsed_key = if key.is_a?(EllipticCurve::PrivateKey)
+      key
+    elsif key.is_a?(String)
+      key_content = if decode_from_base64
+        Base64.decode64(key)
+      else
+        key
+      end
+
+      read_private_key_from_pem(key_content)
+    elsif key_path.present?
+      key_content = File.read(key_path)
+      key_content = Base64.decode64(key_content) if decode_from_base64
+
+      read_private_key_from_pem(key_content)
+    end
+
+    if parsed_key.blank?
+      raise ArgumentError.new("private_key or private_key_path is required")
+    end
+
+    parsed_key
+  end
+end

data/lib/zatca/tag.rb

@@ -0,0 +1,44 @@
+module ZATCA
+  class Tag
+    TAG_IDS = {
+      seller_name: 1,
+      vat_registration_number: 2,
+      timestamp: 3,
+      invoice_total: 4,
+      vat_total: 5,
+      xml_invoice_hash: 6,
+      ecdsa_signature: 7,
+      ecdsa_public_key: 8,
+      ecdsa_stamp_signature: 9 # TODO: is this needed ?
+    }.freeze
+
+    PHASE_1_TAGS = [
+      :seller_name,
+      :vat_registration_number,
+      :timestamp,
+      :invoice_total,
+      :vat_total
+    ].freeze
+
+    attr_accessor :id, :key, :value
+
+    def initialize(key:, value:)
+      @id = TAG_IDS[key]
+      @key = key
+      @value = value.to_s
+    end
+
+    def to_h
+      {id: @id, key: @key, value: @value}
+    end
+
+    def should_be_utf8_encoded?
+      PHASE_1_TAGS.include?(key)
+    end
+
+    def to_tlv
+      tlv = @id.chr + @value.bytesize.chr + @value
+      tlv.force_encoding("ASCII-8BIT")
+    end
+  end
+end

data/lib/zatca/tags.rb

@@ -0,0 +1,46 @@
+require "base64"
+
+module ZATCA
+  class Tags
+    def initialize(tags)
+      keys_to_coerce_to_string = tags.except(:timestamp).keys
+      stringified_tags = tags.map do |key, value|
+        if keys_to_coerce_to_string.include?(key)
+          [key, value.to_s]
+        else
+          [key, value]
+        end
+      end.to_h
+
+      schema_result = TagsSchema.call(stringified_tags)
+      if schema_result.failure?
+        raise(Error, "Parsing tags failed due to:\n#{schema_result.errors(full: true).to_h}")
+      end
+
+      stringified_tags[:timestamp] = tags[:timestamp].to_s
+
+      # Create tags, then sort them by ID
+      @tags = stringified_tags.map do |key, value|
+        Tag.new(key: key, value: value)
+      end.sort_by(&:id)
+    end
+
+    def [](index)
+      @tags[index]
+    end
+
+    def to_base64
+      Base64.strict_encode64(to_tlv)
+    end
+
+    # This is helpful for debugging only, for ZATCA's requirements just call `to_base64`
+    def to_hex_tlv
+      to_tlv.unpack1("H*")
+    end
+
+    # This is helpful for debugging only, for ZATCA's requirements just call `to_base64`
+    def to_tlv
+      @tags.map(&:to_tlv).join("")
+    end
+  end
+end

data/lib/zatca/tags_schema.rb

@@ -0,0 +1,22 @@
+require "dry-schema"
+
+module ZATCA
+  TagsSchema = Dry::Schema.Params do
+    required(:seller_name).filled(:string)
+    required(:vat_registration_number).filled(:string)
+
+    required(:timestamp).filled([:date_time, :string])
+
+    # Using strings to avoid any floating point approximations, we're not doing
+    # any calculations with these values, it's for display purposes only. A
+    # string is a good fit.
+    required(:invoice_total).filled(:string)
+    required(:vat_total).filled(:string)
+
+    # Data types required for Phase 2 by 1 January 2023
+    optional(:xml_invoice_hash).filled(:string)
+    optional(:ecdsa_signature).filled(:string)
+    optional(:ecdsa_public_key).filled(:string)
+    optional(:ecdsa_stamp_signature).filled(:string)
+  end
+end

data/lib/zatca/types.rb

@@ -0,0 +1,7 @@
+require "dry-types"
+
+module ZATCA
+  module Types
+    include Dry.Types()
+  end
+end

data/lib/zatca/ubl/base_component.rb

@@ -0,0 +1,142 @@
+require "dry-initializer"
+require_relative "../types"
+
+class ZATCA::UBL::BaseComponent
+  extend Dry::Initializer
+  attr_accessor :elements, :attributes, :name, :value, :index
+
+  # def self.guard_dig(obj)
+  #   unless obj.respond_to?(:dig)
+  #     raise TypeError, "#{obj.class.name} does not have #dig method"
+  #   end
+  # end
+
+  ArrayOfBaseComponentOrNil = ZATCA::Types::Array.of(ZATCA::Types.Instance(ZATCA::UBL::BaseComponent))
+    .default { [] }
+    .constructor { |value| value.blank? ? [] : value.compact }
+
+  option :elements,
+    type: ArrayOfBaseComponentOrNil,
+    default: proc { [] },
+    optional: true
+
+  option :attributes, type: ZATCA::Types::Strict::Hash, default: proc { {} }, optional: true
+  option :value, type: ZATCA::Types::Coercible::String, default: proc { "" }, optional: true
+  option :name, type: ZATCA::Types::Strict::String, default: proc { "" }, optional: true
+  option :index, type: ZATCA::Types::Coercible::Integer.optional, default: proc {}, optional: true
+
+  # def initialize(elements: [], attributes: {}, value: "", name: "", index: nil)
+  # @elements = elements
+  # @attributes = attributes
+  # @value = value
+  # @name = name
+
+  # # HACK: Add a nil index property to be used for cases where we need
+  # # sequential IDs, this list can be populated after the array is built
+  # @index = index
+  # end
+
+  # There are cases where we end up constructing elements with no content
+  # and we don't want to include them in the final XML.
+  #
+  # This method helps us to return nil if the element has no attributes,
+  # elements or value.
+  #
+  # which is then caught in the `build_xml` method (using `elements.compact`)
+  # and ignored.
+  def self.build(elements: [], attributes: {}, value: "", name: "", index: nil)
+    return nil if elements.blank? && attributes.blank? && value.blank?
+
+    new(elements: elements, attributes: attributes, value: value, name: name, index: index)
+  end
+
+  def [](name)
+    elements.find { |element| element.name == name }
+  end
+
+  def dig(key, *args)
+    value = self[key]
+    return value if args.length == 0 || value.nil?
+    # DigRb.guard_dig(value)
+    value.dig(*args)
+  end
+
+  # TODO: Under Active Development
+  def find_nested_element_by_path(path)
+    path_parts = path.split("/")
+    nested_element = self
+
+    path_parts.each_with_index do |path_part, index|
+      # byebug
+      # next_path_part = path_parts[index + 1]
+      # found_element = nested_element[path_part]
+      # found_next_path_part = found_element[next_path_part]
+
+      # element_with_next_path_part = found_element.find do |child_element|
+      #   child_element.name == next_path_part
+      # end
+      # byebug
+      # nested_element.elements.each do |element|
+      #   byebug
+      #   next_element = element[path_part]
+
+      #   if next_element && next_element[next_path_part]
+      #     nested_element = next_element[next_path_part]
+      #     break
+      #   elsif next_element.present?
+      #     nested_element = next_element
+      #   end
+      # end
+
+      # nested_element = found_element if found_element.present?
+    end
+
+    nested_element
+  end
+
+  def schema
+    self.class.schema
+  end
+
+  def to_h
+    {
+      name => {
+        attributes: attributes,
+        **elements.map(&:to_h),
+        value: value
+      }
+    }
+  end
+
+  def to_xml
+    builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+      xml.root { build_xml(xml) }
+    end
+
+    builder.to_xml
+  end
+
+  def build_xml(xml)
+    xml.send(name, attributes) do
+      if elements.length > 0
+        elements.compact.each { |element| element.build_xml(xml) }
+      elsif value.present?
+        xml.text(value)
+      end
+    end
+  end
+
+  def generate_xml(
+    canonicalized: false,
+    spaces: 2,
+    apply_invoice_hacks: false,
+    remove_root_xml_tag: false
+  )
+    ZATCA::UBL::Builder.new(element: self).build(
+      canonicalized: canonicalized,
+      spaces: spaces,
+      apply_invoice_hacks: apply_invoice_hacks,
+      remove_root_xml_tag: remove_root_xml_tag
+    )
+  end
+end