zatca-sdk 1.1.0

data/lib/zatca/ubl/signing/key_info.rb

@@ -0,0 +1,25 @@
+class ZATCA::UBL::Signing::KeyInfo < ZATCA::UBL::BaseComponent
+  # <ds:KeyInfo>
+  #   <ds:X509Data>
+  #     <ds:X509Certificate>MIID9jCCA5ugAwIBAgITbwAAeCy9aKcLA99HrAABAAB4LDAKBggqhkjOPQQDAjBjMRUwEwYKCZImiZPyLGQBGRYFbG9jYWwxEzARBgoJkiaJk/IsZAEZFgNnb3YxFzAVBgoJkiaJk/IsZAEZFgdleHRnYXp0MRwwGgYDVQQDExNUU1pFSU5WT0lDRS1TdWJDQS0xMB4XDTIyMDQxOTIwNDkwOVoXDTI0MDQxODIwNDkwOVowWTELMAkGA1UEBhMCU0ExEzARBgNVBAoTCjMxMjM0NTY3ODkxDDAKBgNVBAsTA1RTVDEnMCUGA1UEAxMeVFNULS05NzA1NjAwNDAtMzEyMzQ1Njc4OTAwMDAzMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEYYMMoOaFYAhMO/steotfZyavr6p11SSlwsK9azmsLY7b1b+FLhqMArhB2dqHKboxqKNfvkKDePhpqjui5hcn0aOCAjkwggI1MIGaBgNVHREEgZIwgY+kgYwwgYkxOzA5BgNVBAQMMjEtVFNUfDItVFNUfDMtNDdmMTZjMjYtODA2Yi00ZTE1LWIyNjktN2E4MDM4ODRiZTljMR8wHQYKCZImiZPyLGQBAQwPMzEyMzQ1Njc4OTAwMDAzMQ0wCwYDVQQMDAQxMTAwMQwwCgYDVQQaDANUU1QxDDAKBgNVBA8MA1RTVDAdBgNVHQ4EFgQUO5ZiU7NakU3eejVa3I2S1B2sDwkwHwYDVR0jBBgwFoAUdmCM+wagrGdXNZ3PmqynK5k1tS8wTgYDVR0fBEcwRTBDoEGgP4Y9aHR0cDovL3RzdGNybC56YXRjYS5nb3Yuc2EvQ2VydEVucm9sbC9UU1pFSU5WT0lDRS1TdWJDQS0xLmNybDCBrQYIKwYBBQUHAQEEgaAwgZ0wbgYIKwYBBQUHMAGGYmh0dHA6Ly90c3RjcmwuemF0Y2EuZ292LnNhL0NlcnRFbnJvbGwvVFNaRWludm9pY2VTQ0ExLmV4dGdhenQuZ292LmxvY2FsX1RTWkVJTlZPSUNFLVN1YkNBLTEoMSkuY3J0MCsGCCsGAQUFBzABhh9odHRwOi8vdHN0Y3JsLnphdGNhLmdvdi5zYS9vY3NwMA4GA1UdDwEB/wQEAwIHgDAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwMwJwYJKwYBBAGCNxUKBBowGDAKBggrBgEFBQcDAjAKBggrBgEFBQcDAzAKBggqhkjOPQQDAgNJADBGAiEA7mHT6yg85jtQGWp3M7tPT7Jk2+zsvVHGs3bU5Z7YE68CIQD60ebQamYjYvdebnFjNfx4X4dop7LsEBFCNSsLY0IFaQ==</ds:X509Certificate>
+  #   </ds:X509Data>
+  # </ds:KeyInfo>
+
+  def initialize(certificate:)
+    super()
+
+    @certificate = certificate
+  end
+
+  def name
+    "ds:KeyInfo"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "ds:X509Data", elements: [
+        ZATCA::UBL::BaseComponent.new(name: "ds:X509Certificate", value: @certificate)
+      ])
+    ]
+  end
+end

data/lib/zatca/ubl/signing/object.rb

@@ -0,0 +1,20 @@
+class ZATCA::UBL::Signing::Object < ZATCA::UBL::BaseComponent
+  def initialize(signing_time:, cert_digest_value:, cert_issuer_name:, cert_serial_number:)
+    super()
+
+    @signing_time = signing_time
+    @cert_digest_value = cert_digest_value
+    @cert_issuer_name = cert_issuer_name
+    @cert_serial_number = cert_serial_number
+  end
+
+  def name
+    "ds:Object"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::Signing::QualifyingProperties.new(signing_time: @signing_time, cert_digest_value: @cert_digest_value, cert_issuer_name: @cert_issuer_name, cert_serial_number: @cert_serial_number)
+    ]
+  end
+end

data/lib/zatca/ubl/signing/qualifying_properties.rb

@@ -0,0 +1,27 @@
+class ZATCA::UBL::Signing::QualifyingProperties < ZATCA::UBL::BaseComponent
+  def initialize(signing_time:, cert_digest_value:, cert_issuer_name:, cert_serial_number:)
+    super()
+
+    @signing_time = signing_time
+    @cert_digest_value = cert_digest_value
+    @cert_issuer_name = cert_issuer_name
+    @cert_serial_number = cert_serial_number
+  end
+
+  def name
+    "xades:QualifyingProperties"
+  end
+
+  def attributes
+    {
+      "Target" => "signature",
+      "xmlns:xades" => "http://uri.etsi.org/01903/v1.3.2#"
+    }
+  end
+
+  def elements
+    [
+      ZATCA::UBL::Signing::SignedProperties.new(signing_time: @signing_time, cert_digest_value: @cert_digest_value, cert_issuer_name: @cert_issuer_name, cert_serial_number: @cert_serial_number)
+    ]
+  end
+end

data/lib/zatca/ubl/signing/signature.rb

@@ -0,0 +1,50 @@
+class ZATCA::UBL::Signing::Signature < ZATCA::UBL::BaseComponent
+  attr_reader :signing_time, :cert_digest_value, :cert_issuer_name, :cert_serial_number
+
+  def initialize(
+    invoice_hash:, signed_properties_hash:, signature_value:,
+    certificate:, signing_time:, cert_digest_value:, cert_issuer_name:,
+    cert_serial_number:
+  )
+    super()
+
+    @invoice_digest = invoice_hash
+    @signed_properties_hash = signed_properties_hash
+    @signature_value = signature_value
+    @certificate = certificate
+    @signing_time = signing_time
+    @cert_digest_value = cert_digest_value
+    @cert_issuer_name = cert_issuer_name
+    @cert_serial_number = cert_serial_number
+  end
+
+  def attributes
+    {
+      "xmlns:ds" => "http://www.w3.org/2000/09/xmldsig#",
+      "Id" => "signature"
+    }
+  end
+
+  def name
+    "ds:Signature"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::Signing::SignedInfo.new(
+        invoice_digest: @invoice_digest,
+        signed_properties_hash: @signed_properties_hash
+      ),
+
+      ZATCA::UBL::BaseComponent.new(name: "ds:SignatureValue", value: @signature_value),
+      ZATCA::UBL::Signing::KeyInfo.new(certificate: @certificate),
+
+      ZATCA::UBL::Signing::Object.new(
+        signing_time: @signing_time,
+        cert_digest_value: @cert_digest_value,
+        cert_issuer_name: @cert_issuer_name,
+        cert_serial_number: @cert_serial_number
+      )
+    ]
+  end
+end

data/lib/zatca/ubl/signing/signature_information.rb

@@ -0,0 +1,19 @@
+class ZATCA::UBL::Signing::SignatureInformation < ZATCA::UBL::BaseComponent
+  def initialize(signature:)
+    super()
+
+    @signature = signature
+  end
+
+  def name
+    "sac:SignatureInformation"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "cbc:ID", value: "urn:oasis:names:specification:ubl:signature:1"),
+      ZATCA::UBL::BaseComponent.new(name: "sbc:ReferencedSignatureID", value: "urn:oasis:names:specification:ubl:signature:Invoice"),
+      @signature
+    ]
+  end
+end

data/lib/zatca/ubl/signing/signature_properties_reference.rb

@@ -0,0 +1,26 @@
+class ZATCA::UBL::Signing::SignaturePropertiesReference < ZATCA::UBL::BaseComponent
+  attr_accessor :digest_value
+
+  def initialize(digest_value:)
+    super()
+    @digest_value = digest_value
+  end
+
+  def name
+    "ds:Reference"
+  end
+
+  def attributes
+    {
+      "Type" => "http://www.w3.org/2000/09/xmldsig#SignatureProperties",
+      "URI" => "#xadesSignedProperties"
+    }
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "ds:DigestMethod", attributes: {"Algorithm" => "http://www.w3.org/2001/04/xmlenc#sha256"}),
+      ZATCA::UBL::BaseComponent.new(name: "ds:DigestValue", value: @digest_value)
+    ]
+  end
+end

data/lib/zatca/ubl/signing/signed_info.rb

@@ -0,0 +1,21 @@
+class ZATCA::UBL::Signing::SignedInfo < ZATCA::UBL::BaseComponent
+  def initialize(invoice_digest:, signed_properties_hash:)
+    super()
+
+    @invoice_digest = invoice_digest
+    @signed_properties_hash = signed_properties_hash
+  end
+
+  def name
+    "ds:SignedInfo"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "ds:CanonicalizationMethod", attributes: {"Algorithm" => "http://www.w3.org/2006/12/xml-c14n11"}),
+      ZATCA::UBL::BaseComponent.new(name: "ds:SignatureMethod", attributes: {"Algorithm" => "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"}),
+      ZATCA::UBL::Signing::InvoiceSignedDataReference.new(digest_value: @invoice_digest),
+      ZATCA::UBL::Signing::SignaturePropertiesReference.new(digest_value: @signed_properties_hash)
+    ]
+  end
+end

data/lib/zatca/ubl/signing/signed_properties.rb

@@ -0,0 +1,81 @@
+class ZATCA::UBL::Signing::SignedProperties < ZATCA::UBL::BaseComponent
+  def initialize(
+    signing_time:,
+    cert_digest_value:,
+    cert_issuer_name:,
+    cert_serial_number:
+  )
+    super()
+
+    @signing_time = signing_time
+    @cert_digest_value = cert_digest_value
+    @cert_issuer_name = cert_issuer_name
+    @cert_serial_number = cert_serial_number
+  end
+
+  def name
+    "xades:SignedProperties"
+  end
+
+  def attributes
+    {
+      "Id" => "xadesSignedProperties"
+    }
+  end
+
+  def elements
+    [
+      ZATCA::UBL::Signing::SignedSignatureProperties.new(
+        signing_time: @signing_time,
+        cert_digest_value: @cert_digest_value,
+        cert_issuer_name: @cert_issuer_name,
+        cert_serial_number: @cert_serial_number
+      )
+    ]
+  end
+
+  def generate_hash
+    ZATCA::Hashing.generate_hashes(zatca_whitespaced_xml_for_hashing)[:hexdigest_base64]
+  end
+
+  private
+
+  # rubocop:disable Layout/HeredocIndentation
+  # rubocop:disable Layout/ClosingHeredocIndentation
+  #
+  # We need this version of the XML with this exact whitespacing because ZATCA
+  # did not opt for canonicalization before hashing (unlike the invoice hash),
+  # and also because they have XML attributes that are only added the moment you
+  # generate the hash but are expected to be removed in all other instances.
+  #
+  # We will use this version of the XML to generate the hash only, and expect
+  # the output of `build_xml` to generate the non-signing version of the XML.
+  # See:
+  # - https://zatca1.discourse.group/t/what-do-signed-properties-look-like-when-hashing
+  # - https://web.archive.org/web/20230925182417/https://zatca1.discourse.group/t/what-do-signed-properties-look-like-when-hashing/717
+
+  def zatca_whitespaced_xml_for_hashing
+    # Note: chomp is used to get rid of the final newline character
+    <<-XML.chomp
+<xades:SignedProperties xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" Id="xadesSignedProperties">
+                                    <xades:SignedSignatureProperties>
+                                        <xades:SigningTime>#{@signing_time}</xades:SigningTime>
+                                        <xades:SigningCertificate>
+                                            <xades:Cert>
+                                                <xades:CertDigest>
+                                                    <ds:DigestMethod xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
+                                                    <ds:DigestValue xmlns:ds="http://www.w3.org/2000/09/xmldsig#">#{@cert_digest_value}</ds:DigestValue>
+                                                </xades:CertDigest>
+                                                <xades:IssuerSerial>
+                                                    <ds:X509IssuerName xmlns:ds="http://www.w3.org/2000/09/xmldsig#">#{@cert_issuer_name}</ds:X509IssuerName>
+                                                    <ds:X509SerialNumber xmlns:ds="http://www.w3.org/2000/09/xmldsig#">#{@cert_serial_number}</ds:X509SerialNumber>
+                                                </xades:IssuerSerial>
+                                            </xades:Cert>
+                                        </xades:SigningCertificate>
+                                    </xades:SignedSignatureProperties>
+                                </xades:SignedProperties>
+XML
+  end
+  # rubocop:enable Layout/HeredocIndentation
+  # rubocop:enable Layout/ClosingHeredocIndentation
+end

data/lib/zatca/ubl/signing/signed_signature_properties.rb

@@ -0,0 +1,23 @@
+class ZATCA::UBL::Signing::SignedSignatureProperties < ZATCA::UBL::BaseComponent
+  def initialize(signing_time:, cert_digest_value:, cert_issuer_name:, cert_serial_number:)
+    super()
+
+    @signing_time = signing_time
+    @cert_digest_value = cert_digest_value
+    @cert_issuer_name = cert_issuer_name
+    @cert_serial_number = cert_serial_number
+  end
+
+  def name
+    "xades:SignedSignatureProperties"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "xades:SigningTime", value: @signing_time),
+      ZATCA::UBL::BaseComponent.new(name: "xades:SigningCertificate", elements: [
+        ZATCA::UBL::Signing::Cert.new(cert_digest_value: @cert_digest_value, cert_issuer_name: @cert_issuer_name, cert_serial_number: @cert_serial_number)
+      ])
+    ]
+  end
+end

data/lib/zatca/ubl/signing/ubl_document_signatures.rb

@@ -0,0 +1,25 @@
+class ZATCA::UBL::Signing::UBLDocumentSignatures < ZATCA::UBL::BaseComponent
+  def initialize(signature:)
+    super()
+
+    @signature = signature
+  end
+
+  def name
+    "sig:UBLDocumentSignatures"
+  end
+
+  def attributes
+    {
+      "xmlns:sig" => "urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2",
+      "xmlns:sac" => "urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2",
+      "xmlns:sbc" => "urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2"
+    }
+  end
+
+  def elements
+    [
+      ZATCA::UBL::Signing::SignatureInformation.new(signature: @signature)
+    ]
+  end
+end

data/lib/zatca/ubl/signing/ubl_extension.rb

@@ -0,0 +1,22 @@
+class ZATCA::UBL::Signing::UBLExtension < ZATCA::UBL::BaseComponent
+  def initialize(signature:)
+    super()
+
+    @signature = signature
+  end
+
+  def name
+    "ext:UBLExtension"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::BaseComponent.new(name: "ext:ExtensionURI", value: "urn:oasis:names:specification:ubl:dsig:enveloped:xades"),
+      ZATCA::UBL::BaseComponent.new(name: "ext:ExtensionContent", elements: [
+        ZATCA::UBL::Signing::UBLDocumentSignatures.new(signature: @signature)
+      ])
+    ]
+  end
+
+  private
+end

data/lib/zatca/ubl/signing/ubl_extensions.rb

@@ -0,0 +1,17 @@
+class ZATCA::UBL::Signing::UBLExtensions < ZATCA::UBL::BaseComponent
+  def initialize(signature:)
+    super()
+
+    @signature = signature
+  end
+
+  def name
+    "ext:UBLExtensions"
+  end
+
+  def elements
+    [
+      ZATCA::UBL::Signing::UBLExtension.new(signature: @signature)
+    ]
+  end
+end

data/lib/zatca/ubl/signing.rb

@@ -0,0 +1,2 @@
+module ZATCA::UBL::Signing
+end

data/lib/zatca/ubl.rb

@@ -0,0 +1,2 @@
+module ZATCA::UBL
+end

data/lib/zatca/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ZATCA
+  VERSION = "1.1.0"
+end

data/lib/zatca.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "zatca/version"
+require_relative "zatca/types"
+
+require "active_support/all"
+require "zeitwerk"
+require "dry-initializer"
+require "dry-types"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "zatca" => "ZATCA",
+  "qr_code_generator" => "QRCodeGenerator",
+  "qr_code_extractor" => "QRCodeExtractor",
+  "ubl" => "UBL",
+  "csr" => "CSR",
+  "ubl_document_signature" => "UBLDocumentSignature",
+  "ubl_document_signatures" => "UBLDocumentSignatures",
+  "ubl_extension" => "UBLExtension",
+  "ubl_extensions" => "UBLExtensions",
+  "id" => "ID",
+  "ecdsa" => "ECDSA"
+)
+loader.setup
+
+module ZATCA
+  extend self
+
+  class Error < StandardError; end
+
+  def self.extract_qr_base64_from_base64_invoice(base64_invoice)
+    QRCodeExtractor.new(invoice_base64: base64_invoice).extract
+  end
+
+  def self.render_qr_code(tags: nil, base64: nil)
+    if tags.present?
+      tags = ZATCA::Tags.new(tags) if tags.is_a?(Hash)
+      QRCodeGenerator.new(tags: tags).render
+    elsif base64.present?
+      QRCodeGenerator.new(base64: base64).render
+    else
+      raise ArgumentError, "Either tags or base64 must be provided"
+    end
+  end
+end
+
+loader.eager_load

data/zatca_sdk.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "lib/zatca/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "zatca-sdk"
+  spec.version = ZATCA::VERSION
+  spec.authors = ["Omar Bahareth"]
+  spec.email = ["omar@omar.engineer"]
+
+  spec.summary = "A library for generating QR Codes for the e-invoice standard by ZATCA in Saudi Arabia."
+  spec.description = "A library for generating QR Codes for the e-invoice standard by ZATCA in Saudi Arabia."
+  spec.homepage = "https://github.com/obahareth/zatca"
+  spec.required_ruby_version = ">= 2.5.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/obahareth/zatca"
+  spec.metadata["changelog_uri"] = "https://github.com/obahareth/zatca/releases"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features|einvoicing-sdk)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_dependency "zeitwerk", "~> 2.4"
+  spec.add_dependency "dry-schema", ">= 1.5"
+  spec.add_dependency "rqrcode", "~> 2.1.0"
+  spec.add_dependency "httpx", "~> 0.21.0"
+  spec.add_dependency "nokogiri", ">= 1.12"
+  spec.add_dependency "activesupport", ">= 5.2"
+  spec.add_dependency "dry-initializer", ">= 3.0"
+  spec.add_dependency "starkbank-ecdsa", "~> 2.0"
+
+  # Development Dependencies
+  spec.add_development_dependency "standard", "~> 1.3"
+  spec.add_development_dependency "byebug", "~> 9.0"
+  spec.add_development_dependency "rspec", "~> 3.10"
+  spec.add_development_dependency "vcr", "~> 6.0.0"
+  spec.add_development_dependency "webmock", "~> 3.18.1"
+  spec.add_development_dependency "amazing_print", "~> 1.4.0"
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end