zatca 0.1.2 → 1.0.1

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

@@ -5,9 +5,21 @@ module ZATCA
       vat_registration_number: 2,
       timestamp: 3,
       invoice_total: 4,
-      vat_total: 5
+      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:)
@@ -20,14 +32,12 @@ module ZATCA
       {id: @id, key: @key, value: @value}
     end
 
-    def to_tlv
-      # TLV should be concatenated together without any separator in the following
-      # format: character_value_of_id character_value_of_value_length value_itself
-      # All of this should be in 8-bit ASCII.
-      tlv = @id.chr + @value.bytesize.chr + value
+    def should_be_utf8_encoded?
+      PHASE_1_TAGS.include?(key)
+    end
 
-      # We need to use force_encoding because encode will raise errors when
-      # trying to encode a string with utf-8 characters.
+    def to_tlv
+      tlv = @id.chr + @value.bytesize.chr + @value
       tlv.force_encoding("ASCII-8BIT")
     end
   end

data/lib/zatca/tags.rb

@@ -33,8 +33,12 @@ module ZATCA
       Base64.strict_encode64(to_tlv)
     end
 
-    private
+    # 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

data/lib/zatca/tags_schema.rb

@@ -13,10 +13,10 @@ module ZATCA
     required(:invoice_total).filled(:string)
     required(:vat_total).filled(:string)
 
-    # TODO: Data types required by 1 January 2023
-    # - Hash of XML Invoice
-    # - ECDSA signature
-    # - ECDSA public key
-    # - ECDSA signature of the cryptographic stamp’s public key by ZATCA’s technical CA
+    # 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

data/lib/zatca/ubl/builder.rb

@@ -0,0 +1,166 @@
+class ZATCA::UBL::Builder
+  extend Dry::Initializer
+
+  option :element, type: ZATCA::Types.Instance(ZATCA::UBL::BaseComponent)
+
+  def build(
+    canonicalized: false,
+    spaces: 4,
+    apply_invoice_hacks: false,
+    remove_root_xml_tag: false
+  )
+    @remove_root_xml_tag = remove_root_xml_tag
+
+    builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+      element.build_xml(xml)
+    end
+
+    xml = if canonicalized
+      canonicalized_xml(builder: builder)
+    else
+      uncanonicalized_xml(builder: builder, spaces: spaces)
+    end
+
+    xml = apply_hacks_to_invoice(element, xml) if apply_invoice_hacks
+
+    xml
+  end
+
+  private
+
+  # ZATCA sadly requires very specific and unconventional indentation in the XML
+  # when it is pretty (uncanonicalized), the only way we can accomplish this is
+  # to find and replace blocks manually.
+  def apply_hacks_to_invoice(element, xml)
+    return xml unless element.is_a?(ZATCA::UBL::Invoice)
+
+    apply_qualifying_properties_hacks(element, xml)
+  end
+
+  def apply_qualifying_properties_hacks(invoice, xml)
+    return xml if invoice.qualifying_properties.blank?
+
+    regex = ZATCA::Hacks.qualifying_properties_regex
+
+    xml.gsub(regex, invoice.qualifying_properties)
+  end
+
+  # This function does not produce canonicalization matching C14N 1.1, it applies
+  # C14N 1.1 then manually adds back the whitespace in the format that ZATCA
+  # expects.
+  def canonicalized_xml(builder:)
+    builder.doc.canonicalize(Nokogiri::XML::XML_C14N_1_1)
+
+    # TODO: In case ZATCA ever asks us to use their whitespace format again.
+    # In some meetings they say we have to use it, in some meetings they say
+    # we don't. The simpler approach is that we don't use it.
+    #
+    # ZATCA's docs specifically state we must use C14N 1.1 canonicalization.
+    # xml = uncanonicalized_xml(builder: builder, spaces: 4)
+    # xml_doc = Nokogiri::XML(xml)
+
+    # canonical_xml = xml_doc.canonicalize(Nokogiri::XML::XML_C14N_1_1)
+
+    # canonical_xml
+  end
+
+  def uncanonicalized_xml(builder:, spaces: 4)
+    builder.to_xml(indent: spaces.to_i)
+
+    # xml = builder.to_xml(indent: spaces.to_i)
+    # xml = match_xml_string_to_zatca_whitespaces(xml)
+    # xml
+  end
+
+  def match_xml_string_to_zatca_whitespaces(xml)
+    # ZATCA has elements that are not spaced by multiples of 4, and random new
+    # lines with trailing whitespaces, so we need to manually adjust our
+    # indentation to match ZATCA's.
+    zatca_weird_whitespaces.each do |whitespace_hash|
+      xml.gsub!(whitespace_hash[:our_version], whitespace_hash[:zatca_version])
+    end
+
+    # Canonicalization already removes the root XML tag for us, but since we had
+    # to create a new uncanonicalized document for ZATCA's invoice hacks, we
+    # have to remove it manually.
+    if @remove_root_xml_tag
+      xml.gsub!("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n", "")
+    end
+
+    # ZATCA Removes the final newline character, so we do the same
+    xml.chomp
+
+    # This part is not clear, ZATCA shared documents with us that use CRLF
+    # but the samples in the SDK use LF, so we're not sure which one is correct.
+    # ZATCA wants CRLF (\r\n) in their canonicalized form instead of just LF (\n)
+    xml.gsub!("\n", "\r\n")
+
+    xml
+  end
+
+  # Not sure if this is needed, in some meetings ZATCA says you have to match
+  # their whitspace exactly and in some meetings they say you don't.
+  # HACK: This is really hacky, using regexes or XPaths would be better, but
+  # that wasn't easy to build and maintain, so we're using this if/until we run
+  # into issues.
+  #
+  # We may eventually go to an approach where we just have hardcoded XML in each
+  # element's file and we just add in the values instead of generating our own
+  # XML if this gets too hard to maintain.
+  def zatca_weird_whitespaces
+    @_zatca_weird_whitespaces ||= [
+      {
+        our_version: "<cbc:ProfileID>",
+        zatca_version: "\n    <cbc:ProfileID>"
+      },
+      {
+        our_version: "<cac:AccountingSupplierParty>",
+        zatca_version: "\n    \n    <cac:AccountingSupplierParty>"
+      },
+      {
+        our_version: "                <cbc:CompanyID>",
+        zatca_version: "                    <cbc:CompanyID>"
+      },
+      {
+        our_version: "            <cac:TaxCategory>",
+        zatca_version: "             <cac:TaxCategory>"
+      },
+      {
+        our_version: "            </cac:TaxCategory>",
+        zatca_version: "             </cac:TaxCategory>"
+      },
+      {
+        our_version: '                <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>',
+        zatca_version: '                 <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>'
+      },
+      {
+        our_version: "<cac:TaxScheme>\n                    <cbc:ID schemeAgencyID=\"6\" schemeID=\"UN/ECE 5153\">VAT</cbc:ID>",
+        zatca_version: "<cac:TaxScheme>\n                   <cbc:ID schemeAgencyID=\"6\" schemeID=\"UN/ECE 5153\">VAT</cbc:ID>"
+      },
+      {
+        our_version: "<cac:TaxTotal>\n            <cbc:TaxAmount currencyID=\"SAR\">",
+        zatca_version: "<cac:TaxTotal>\n             <cbc:TaxAmount currencyID=\"SAR\">"
+      },
+      {
+        our_version: "            <cbc:RoundingAmount currencyID=\"SAR\">",
+        zatca_version: "             <cbc:RoundingAmount currencyID=\"SAR\">"
+      },
+      {
+        our_version: "                <cbc:ChargeIndicator>",
+        zatca_version: "               <cbc:ChargeIndicator>"
+      },
+      {
+        our_version: "                <cbc:AllowanceChargeReason>",
+        zatca_version: "               <cbc:AllowanceChargeReason>"
+      },
+      {
+        our_version: "                <cbc:Amount currencyID=\"SAR\">",
+        zatca_version: "               <cbc:Amount currencyID=\"SAR\">"
+      },
+      {
+        our_version: "<cbc:ID schemeAgencyID=\"6\" schemeID=\"UN/ECE 5305\">S</cbc:ID>\n                <cbc:Percent>",
+        zatca_version: "<cbc:ID schemeAgencyID=\"6\" schemeID=\"UN/ECE 5305\">S</cbc:ID>\n                 <cbc:Percent>"
+      }
+    ]
+  end
+end

data/lib/zatca/ubl/common_aggregate_components/allowance_charge.rb

@@ -0,0 +1,64 @@
+class ZATCA::UBL::CommonAggregateComponents::AllowanceCharge < ZATCA::UBL::BaseComponent
+  attr_accessor :id, :charge_indicator, :allowance_charge_reason, :amount
+
+  #   <cac:AllowanceCharge>
+  #   <cbc:ID>1</cbc:ID>
+  #   <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
+  #   <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
+  #   <cbc:Amount currencyID="SAR">2</cbc:Amount>
+  #   <cac:TaxCategory>
+  #       <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>
+  #       <cbc:Percent>15</cbc:Percent>
+  #       <cac:TaxScheme>
+  #           <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
+  #       </cac:TaxScheme>
+  #   </cac:TaxCategory>
+  # </cac:AllowanceCharge>
+
+  def initialize(
+    charge_indicator:, allowance_charge_reason:, amount:, currency_id: "SAR",
+    tax_category: nil, add_tax_category: true, add_id: true, tax_categories: []
+  )
+    super()
+
+    @charge_indicator = charge_indicator.to_s
+
+    @allowance_charge_reason = allowance_charge_reason
+    @amount = amount
+    @currency_id = currency_id
+
+    @add_tax_category = add_tax_category
+    @tax_category = tax_category
+    @add_id = add_id
+
+    if add_tax_category && @tax_category.blank?
+      @tax_category = ZATCA::UBL::CommonAggregateComponents::TaxCategory.new
+    end
+
+    @tax_categories = if @tax_category.present? && tax_categories.blank?
+      [@tax_category]
+    else
+      tax_categories
+    end
+  end
+
+  def name
+    "cac:AllowanceCharge"
+  end
+
+  def id_element
+    if @add_id && index.present?
+      ZATCA::UBL::BaseComponent.new(name: "cbc:ID", value: index)
+    end
+  end
+
+  def elements
+    [
+      id_element,
+      ZATCA::UBL::BaseComponent.new(name: "cbc:ChargeIndicator", value: @charge_indicator),
+      ZATCA::UBL::BaseComponent.new(name: "cbc:AllowanceChargeReason", value: @allowance_charge_reason),
+      ZATCA::UBL::BaseComponent.new(name: "cbc:Amount", value: @amount, attributes: {"currencyID" => @currency_id}),
+      *@tax_categories
+    ]
+  end
+end

data/lib/zatca/ubl/common_aggregate_components/classified_tax_category.rb

@@ -0,0 +1,25 @@
+class ZATCA::UBL::CommonAggregateComponents::ClassifiedTaxCategory < ZATCA::UBL::BaseComponent
+  attr_reader :scheme_id, :id
+
+  def initialize(id: "S", percent: "15.00", tax_scheme_id: "VAT")
+    super()
+
+    @id = id
+    @percent = percent
+    @tax_scheme_id = tax_scheme_id
+  end
+
+  def name
+    "cac:ClassifiedTaxCategory"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "cbc:ID", value: @id),
+      ZATCA::UBL::BaseComponent.new(name: "cbc:Percent", value: @percent),
+      ZATCA::UBL::BaseComponent.new(name: "cac:TaxScheme", elements: [
+        ZATCA::UBL::BaseComponent.new(name: "cbc:ID", value: @tax_scheme_id)
+      ])
+    ]
+  end
+end

data/lib/zatca/ubl/common_aggregate_components/delivery.rb

@@ -0,0 +1,27 @@
+class ZATCA::UBL::CommonAggregateComponents::Delivery < ZATCA::UBL::BaseComponent
+  attr_reader :scheme_id, :id
+
+  def initialize(actual_delivery_date:, latest_delivery_date: nil)
+    super()
+
+    @latest_delivery_date = latest_delivery_date
+    @actual_delivery_date = actual_delivery_date
+  end
+
+  def name
+    "cac:Delivery"
+  end
+
+  def latest_delivery_date_element
+    return nil if @latest_delivery_date.nil?
+
+    ZATCA::UBL::BaseComponent.new(name: "cbc:LatestDeliveryDate", value: @latest_delivery_date)
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "cbc:ActualDeliveryDate", value: @actual_delivery_date),
+      latest_delivery_date_element
+    ]
+  end
+end

data/lib/zatca/ubl/common_aggregate_components/invoice_line.rb

@@ -0,0 +1,63 @@
+class ZATCA::UBL::CommonAggregateComponents::InvoiceLine < ZATCA::UBL::BaseComponent
+  # <cac:InvoiceLine>
+  # <cbc:ID>1</cbc:ID>
+  # <cbc:InvoicedQuantity unitCode="PCE">44.000000</cbc:InvoicedQuantity>
+  # <cbc:LineExtensionAmount currencyID="SAR">966.00</cbc:LineExtensionAmount>
+  # <cac:TaxTotal>
+  #     <cbc:TaxAmount currencyID="SAR">144.90</cbc:TaxAmount>
+  #     <cbc:RoundingAmount currencyID="SAR">1110.90</cbc:RoundingAmount>
+
+  # </cac:TaxTotal>
+  # <cac:Item>
+  #     <cbc:Name>dsd</cbc:Name>
+  #     <cac:ClassifiedTaxCategory>
+  #         <cbc:ID>S</cbc:ID>
+  #         <cbc:Percent>15.00</cbc:Percent>
+  #         <cac:TaxScheme>
+  #             <cbc:ID>VAT</cbc:ID>
+  #         </cac:TaxScheme>
+  #     </cac:ClassifiedTaxCategory>
+  # </cac:Item>
+  # <cac:Price>
+  #     <cbc:PriceAmount currencyID="SAR">22.00</cbc:PriceAmount>
+  #     <cac:AllowanceCharge>
+  #         <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
+  #         <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
+  #         <cbc:Amount currencyID="SAR">2.00</cbc:Amount>
+  #     </cac:AllowanceCharge>
+  # </cac:Price>
+  # </cac:InvoiceLine>
+
+  def initialize(
+    invoiced_quantity:, invoiced_quantity_unit_code:,
+    line_extension_amount:, tax_total:, item:,
+    price:, allowance_charge: nil, currency_id: "SAR"
+  )
+    super()
+
+    @invoiced_quantity = invoiced_quantity
+    @invoiced_quantity_unit_code = invoiced_quantity_unit_code
+    @line_extension_amount = line_extension_amount
+    @tax_total = tax_total
+    @item = item
+    @price = price
+    @allowance_charge = allowance_charge
+    @currency_id = currency_id
+  end
+
+  def name
+    "cac:InvoiceLine"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "cbc:ID", value: index),
+      ZATCA::UBL::BaseComponent.new(name: "cbc:InvoicedQuantity", value: @invoiced_quantity, attributes: {unitCode: @invoiced_quantity_unit_code}),
+      ZATCA::UBL::BaseComponent.new(name: "cbc:LineExtensionAmount", value: @line_extension_amount, attributes: {currencyID: @currency_id}),
+      @tax_total,
+      @item,
+      @price,
+      @allowance_charge
+    ]
+  end
+end

data/lib/zatca/ubl/common_aggregate_components/item.rb

@@ -0,0 +1,21 @@
+class ZATCA::UBL::CommonAggregateComponents::Item < ZATCA::UBL::BaseComponent
+  attr_reader :scheme_id, :id
+
+  def initialize(name:, classified_tax_category: nil)
+    super()
+
+    @name = name
+    @classified_tax_category = classified_tax_category || ZATCA::UBL::CommonAggregateComponents::ClassifiedTaxCategory.new
+  end
+
+  def name
+    "cac:Item"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "cbc:Name", value: @name),
+      @classified_tax_category
+    ]
+  end
+end