zatca 0.1.2 → 1.0.0

data/einvoicing-sdk/install.bat

@@ -0,0 +1,74 @@
+
+@echo off
+
+SET MY_PATH=%~dp0
+
+setx /U %USERDOMAIN%/%USERNAME% /S %COMPUTERNAME% SDK_CONFIG %MY_PATH%Configuration/config.json
+setx /U %USERDOMAIN%/%USERNAME% /S %COMPUTERNAME% FATOORA_HOME %MY_PATH%Apps\ 
+SETX PATH ""
+SETX PATH "%MY_PATH%Apps\;%PATH%"
+
+cd Configuration
+
+set "CURRENT=%~dp0"
+set "_path=%CURRENT%Configuration"
+
+for %%a in (%_path:~0,-1%) do set "p2_dir=%%~dpa"\
+
+set p2_dir=%p2_dir:\=\\%
+
+SET XSD=
+FOR /F %%I IN ('jq .xsdPath defaults.json ') DO set "XSD=%%I"
+
+SET XSD_filename=
+for %%F in (%XSD%) do  set "XSD_filename=%%~nxF"
+
+SET EN_SCHEMA=
+FOR /F %%I IN ('jq .enSchematron defaults.json ') DO set "EN_SCHEMA=%%I"
+SET EN_SCHEMA_filename=
+for %%F in (%EN_SCHEMA%) do  set "EN_SCHEMA_filename=%%~nxF"
+
+
+SET ZATCA_SCHEMA=
+FOR /F %%I IN ('jq .zatcaSchematron defaults.json ') DO set "ZATCA_SCHEMA=%%I"
+SET ZATCA_SCHEMA_filename=
+for %%F in (%ZATCA_SCHEMA%) do  set "ZATCA_SCHEMA_filename=%%~nxF"
+
+SET CERT=
+FOR /F %%I IN ('jq .certPath defaults.json ') DO set "CERT=%%I"
+SET CERT_filename=
+for %%F in (%CERT%) do  set "CERT_filename=%%~nxF"
+
+SET PK=
+FOR /F %%I IN ('jq .privateKeyPath defaults.json ') DO set "PK=%%I"
+SET PK_filename=
+for %%F in (%PK%) do  set "PK_filename=%%~nxF"
+
+SET PIH=
+FOR /F %%I IN ('jq .pihPath defaults.json ') DO set "PIH=%%I"
+SET PIH_filename=
+for %%F in (%PIH%) do  set "PIH_filename=%%~nxF"
+
+SET CERT_PASSWORD=
+FOR /F %%I IN ('jq .certPassword defaults.json ') DO set "CERT_PASSWORD=%%I"
+SET CERT_PASSWORD_VALUE=
+for %%F in (%CERT_PASSWORD%) do  set "CERT_PASSWORD_VALUE=%%~nxF"
+
+SET usage=
+FOR /F %%I IN ('jq .usagePathFile defaults.json ') DO set "usage=%%I"
+SET usage_filename=
+for %%F in (%usage%) do  set "usage_filename=%%~nxF"
+
+
+echo {	"xsdPath" : "%p2_dir%Data\\Schemas\\xsds\\UBL2.1\\xsd\\maindoc\\%XSD_filename%",  ^
+		"enSchematron":"%p2_dir%Data\\Rules\\schematrons\\%EN_SCHEMA_filename%", ^
+		"zatcaSchematron":"%p2_dir%Data\\Rules\\schematrons\\%ZATCA_SCHEMA_filename%", ^
+		"certPath":"%p2_dir%Data\\Certificates\\%CERT_filename%",^
+		"privateKeyPath":"%p2_dir%Data\\Certificates\\%PK_filename%",^
+		"pihPath" : "%p2_dir%Data\\PIH\\%PIH_filename%",^
+        	"certPassword" : "%CERT_PASSWORD_VALUE%",^
+		"inputPath" : "%p2_dir%Data\\Input",^
+		"usagePathFile":"%p2_dir%Configuration\\%usage_filename%"^
+     } > config.json
+
+cd ../

data/einvoicing-sdk/install.sh

@@ -0,0 +1,74 @@
+
+export FATOORA_HOME="${PWD}"
+
+export PATH=$PATH:$FATOORA_HOME/Apps/
+#export PATH
+#export FATOORA_HOME
+
+
+
+touch ~/.zshrc
+touch ~/.bash-profile
+
+
+
+
+SDK_CONFIG="${PWD}/Configuration/config.json"
+
+
+echo "export PATH=$PATH:$FATOORA_HOME/Apps/" >> ~/.bash-profile
+echo "export FATOORA_HOME=${PWD}/Apps" >> ~/.bash-profile
+echo "export SDK_CONFIG=$SDK_CONFIG" >> ~/.bash-profile
+
+echo "export PATH=$PATH:$FATOORA_HOME/Apps/" >> ~/.zshrc
+echo "export FATOORA_HOME=${PWD}/Apps" >> ~/.zshrc
+echo "export SDK_CONFIG=$SDK_CONFIG" >> ~/.zshrc
+
+
+
+
+
+source ~/.bash-profile
+source ~/.zshrc
+
+cd Configuration
+
+parentDir="$(dirname "$PWD")"
+
+xsdPath=$(jq -r '.xsdPath' defaults.json)
+xsdPathFileName="$(basename $xsdPath)"
+
+enSchematron=$(jq -r '.enSchematron' defaults.json)
+enSchematronFileName="$(basename $enSchematron)"
+
+zatcaSchematron=$(jq -r '.zatcaSchematron' defaults.json)
+zatcaSchematronFileName="$(basename $zatcaSchematron)"
+
+certPath=$(jq -r '.certPath' defaults.json)
+certPathFileName="$(basename $certPath)"
+
+pkPath=$(jq -r '.privateKeyPath' defaults.json)
+pkPathFileName="$(basename $pkPath)"
+
+pihPath=$(jq -r '.pihPath' defaults.json)
+pihPathFileName="$(basename $pihPath)"
+
+certPassword=$(jq -r '.certPassword' defaults.json)
+certPasswordValue="$(basename $certPassword)"
+
+usagePath=$(jq -r '.usagePathFile' defaults.json)
+usagePathFileName="$(basename $usagePath)"
+
+
+jq -n '{"xsdPath":$one, "enSchematron":$two, "zatcaSchematron":$thr,"certPath":$fou, "privateKeyPath":$fiv  ,"pihPath":$six ,"certPassword":$sev ,"inputPath":$eight,"usagePathFile":$nine}' \
+  --arg one "${parentDir}/Data/Schemas/xsds/UBL2.1/xsd/maindoc/$xsdPathFileName" \
+  --arg two "${parentDir}/Data/Rules/schematrons/$enSchematronFileName"   \
+  --arg thr "${parentDir}/Data/Rules/schematrons/$zatcaSchematronFileName" \
+  --arg fou "${parentDir}/Data/Certificates/$certPathFileName" \
+  --arg fiv "${parentDir}/Data/Certificates/$pkPathFileName" \
+  --arg six "${parentDir}/Data/PIH/$pihPathFileName"  \
+  --arg sev "$certPasswordValue"  \
+  --arg eight "${parentDir}/Data/Input"  \
+  --arg nine "${parentDir}/Configuration/$usagePathFileName"  >config.json
+
+cd ../

data/lib/zatca/client.rb

@@ -0,0 +1,173 @@
+require "httpx"
+require "json"
+
+# This wraps the API described here:
+# https://sandbox.zatca.gov.sa/IntegrationSandbox
+class ZATCA::Client
+  # API URLs are not present in developer portal, they can only be found in a PDF
+  # called Fatoora Portal User Manual, here:
+  # https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/Fatoora%20portal%20user%20manual.pdf
+  PRODUCTION_BASE_URL = "https://gw-fatoora.zatca.gov.sa/e-invoicing/core".freeze
+  SANDBOX_BASE_URL = "https://gw-apic-gov.gazt.gov.sa/e-invoicing/developer-portal".freeze
+  SIMULATION_BASE_URL = "https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation".freeze
+
+  ENVIRONMENTS_TO_URLS_MAP = {
+    production: PRODUCTION_BASE_URL,
+    sandbox: SANDBOX_BASE_URL,
+    simulation: SIMULATION_BASE_URL
+  }.freeze
+
+  DEFAULT_API_VERSION = "V2".freeze
+  LANGUAGES = %w[ar en].freeze
+
+  def initialize(username:, password:, language: "ar", version: DEFAULT_API_VERSION, environment: :production)
+    raise "Invalid language: #{language}, Please use one of: #{LANGUAGES}" unless LANGUAGES.include?(language)
+
+    @username = username
+    @password = password
+    @language = language
+    @version = version
+
+    @base_url = ENVIRONMENTS_TO_URLS_MAP[environment.to_sym] || PRODUCTION_BASE_URL
+  end
+
+  # Reporting API
+  def report_invoice(uuid:, invoice_hash:, invoice:, cleared:)
+    request(
+      path: "invoices/reporting/single",
+      method: :post,
+      body: {
+        uuid: uuid,
+        invoiceHash: invoice_hash,
+        invoice: invoice
+      },
+      headers: {
+        "Clearance-Status" => cleared ? "1" : "0"
+      }
+    )
+  end
+
+  # Clearance API
+  def clear_invoice(uuid:, invoice_hash:, invoice:, cleared:)
+    request(
+      path: "invoices/clearance/single",
+      method: :post,
+      body: {
+        uuid: uuid,
+        invoiceHash: invoice_hash,
+        invoice: invoice
+      },
+      headers: {
+        "Clearance-Status" => cleared ? "1" : "0"
+      }
+    )
+  end
+
+  # Compliance CSID API
+  # This should be used to obtain credentials to issue a certificate in the next
+  # request (issue_production_csid)
+  #
+  # csid stands for Cryptographic Stamp Identifier
+  #
+  # csr stands for Certificate Signing Request
+  #     You should generate this via the ZATCA::Signing::CSR class
+  #
+  # otp stands for One Time Password.
+  #     You can get this from the fatoora portal
+  # Returns:
+  # {
+  #   "binarySecurityToken": "string" # To be used as a username in next request
+  #   "secret": "string" # To be used as a password in next request
+  # }
+  def issue_csid(csr:, otp:)
+    request(
+      path: "compliance",
+      method: :post,
+      body: {csr: csr},
+      headers: {"OTP" => otp},
+      authenticated: false
+    )
+  end
+
+  # Compliance Invoice API
+  def compliance_check(uuid:, invoice_hash:, invoice:)
+    request(
+      path: "compliance/invoices",
+      method: :post,
+      body: {
+        uuid: uuid,
+        invoiceHash: invoice_hash,
+        invoice: invoice
+      }
+    )
+  end
+
+  # Production CSID (Onboarding) API
+  # This endpoint gives you the Base64-encoded certificate back
+  # compliance_request_id is retrieved from the issue_csid request, and is
+  # in the response as responseID
+  def issue_production_csid(compliance_request_id:)
+    request(
+      path: "production/csids",
+      method: :post,
+      body: {compliance_request_id: compliance_request_id}
+    )
+  end
+
+  # Production CSID (Renewal) API
+  # csr stands for Certificate Signing Request
+  # otp stands for One Time Password
+  def renew_production_csid(otp:, csr:)
+    request(
+      path: "production/csids",
+      method: :patch,
+      body: {csr: csr},
+      headers: {"OTP" => otp}
+    )
+  end
+
+  private
+
+  def request(method:, path:, body: {}, headers: {}, authenticated: true)
+    url = "#{@base_url}/#{path}"
+    headers = default_headers.merge(headers)
+
+    client = if authenticated
+      authenticated_request_cilent
+    else
+      unauthenticated_request_client
+    end
+
+    response = client.send(method, url, json: body, headers: headers)
+
+    response_body = response.body.to_s
+
+    if response.headers["Content-Type"] == "application/json"
+      parse_json_or_return_string(response_body)
+    else
+      response_body
+    end
+  end
+
+  def authenticated_request_cilent
+    HTTPX.plugin(:basic_authentication).basic_auth(@username, @password)
+  end
+
+  def unauthenticated_request_client
+    HTTPX
+  end
+
+  def default_headers
+    {
+      "Accept-Language" => @language,
+      "Content-Type" => "application/json",
+      "Accept-Version" => @version
+    }
+  end
+
+  def parse_json_or_return_string(json)
+    JSON.parse(json)
+  rescue JSON::ParserError
+    json
+  end
+end

data/lib/zatca/hacks.rb

@@ -0,0 +1,45 @@
+module ZATCA::Hacks
+  extend self
+
+  # rubocop:disable Layout/HeredocIndentation
+  # rubocop:disable Layout/ClosingHeredocIndentation
+  # ZATCA also hashes serverside to ensure our signed properties hash is correct.
+  # However ZATCA does not format the XML to use the same whitespace needed for
+  # hashing. They generate the hash using the whitespace as you sent it, so to
+  # account for that we need to ensure we use the same exact whitespace as them.
+  #
+  # Due to the way our SDK works, we will sadly not be able to use the same
+  # generated XML, we need to use ZATCA's specific spacing.
+  # So we will generate the entire XML first then replace the qualifying
+  # properties block to account for this.
+  def zatca_indented_qualifying_properties(signing_time:, cert_digest_value:, cert_issuer_name:, cert_serial_number:)
+    <<-XML.chomp
+                            <xades:QualifyingProperties xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" Target="signature">
+                                <xades:SignedProperties Id="xadesSignedProperties">
+                                    <xades:SignedSignatureProperties>
+                                        <xades:SigningTime>#{signing_time}</xades:SigningTime>
+                                        <xades:SigningCertificate>
+                                            <xades:Cert>
+                                                <xades:CertDigest>
+                                                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
+                                                    <ds:DigestValue>#{cert_digest_value}</ds:DigestValue>
+                                                </xades:CertDigest>
+                                                <xades:IssuerSerial>
+                                                    <ds:X509IssuerName>#{cert_issuer_name}</ds:X509IssuerName>
+                                                    <ds:X509SerialNumber>#{cert_serial_number}</ds:X509SerialNumber>
+                                                </xades:IssuerSerial>
+                                            </xades:Cert>
+                                        </xades:SigningCertificate>
+                                    </xades:SignedSignatureProperties>
+                                </xades:SignedProperties>
+                            </xades:QualifyingProperties>
+  XML
+  end
+
+  # rubocop:enable Layout/HeredocIndentation
+  # rubocop:enable Layout/ClosingHeredocIndentation
+
+  def qualifying_properties_regex
+    /[ ]*<xades:QualifyingProperties.*?<\/xades:QualifyingProperties>/m
+  end
+end

data/lib/zatca/hashing.rb

@@ -0,0 +1,18 @@
+class ZATCA::Hashing
+  # Returns the content as:
+  # - hash - SHA256 digest (bytes)
+  # - hexdigest - SHA256 digest (hex)
+  # - base64 - SHA256 digest (bytes) then Base64 encoded
+  # - hexdigest_base64 - SHA256 digest (hex) then Base64 encoded
+  def self.generate_hashes(content)
+    sha256 = Digest::SHA256.digest(content)
+    sha256_hex = Digest::SHA256.hexdigest(content)
+
+    {
+      base64: Base64.strict_encode64(sha256),
+      hexdigest_base64: Base64.strict_encode64(sha256_hex),
+      hexdigest: sha256_hex,
+      hash: sha256
+    }
+  end
+end

data/lib/zatca/qr_code_extractor.rb

@@ -0,0 +1,31 @@
+require "nokogiri"
+require "base64"
+
+class ZATCA::QRCodeExtractor
+  attr_reader :invoice_base64
+
+  def initialize(invoice_base64:)
+    @invoice_base64 = invoice_base64
+  end
+
+  def extract
+    xml_invoice = Base64.strict_decode64(invoice_base64)
+    extract_qr_code_base64_from_xml(xml_invoice)
+  end
+
+  private
+
+  def extract_qr_code_base64_from_xml(xml)
+    # Read Invoice
+    doc = Nokogiri::XML(xml)
+
+    # Extract QR Code by XPath
+    qr_code_node = doc.xpath(qr_code_xpath)&.first
+
+    qr_code_node.present? ? qr_code_node.text : nil
+  end
+
+  def qr_code_xpath
+    "//cac:AdditionalDocumentReference[cbc:ID='QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject"
+  end
+end

data/lib/zatca/qr_code_generator.rb

@@ -2,8 +2,9 @@ require "rqrcode"
 
 module ZATCA
   class QRCodeGenerator
-    def initialize(tags)
+    def initialize(tags: nil, base64: nil)
       @tags = tags
+      @base64 = base64
     end
 
     def render(size: 256)
@@ -15,7 +16,13 @@ module ZATCA
     private
 
     def generate
-      RQRCode::QRCode.new(@tags.to_base64)
+      if @tags.present?
+        RQRCode::QRCode.new(@tags.to_base64)
+      elsif @base64.present?
+        RQRCode::QRCode.new(@base64)
+      else
+        raise ArgumentError, "Either tags or base64 must be provided"
+      end
     end
   end
 end

data/lib/zatca/signing/certificate.rb

@@ -0,0 +1,78 @@
+class ZATCA::Signing::Certificate
+  attr_accessor :serial_number, :issuer_name, :cert_content_without_headers,
+    :hash, :public_key, :public_key_without_headers, :signature,
+    :public_key_bytes
+
+  # Returns the certificate hashed with SHA256 then Base64 encoded
+  def self.generate_base64_hash(base64_certificate)
+    ZATCA::Hashing.generate_hashes(base64_certificate)[:hexdigest_base64]
+  end
+
+  def self.read_certificate(certificate_path)
+    certificate = OpenSSL::X509::Certificate.new(File.read(certificate_path))
+
+    new(openssl_certificate: certificate)
+  end
+
+  def initialize(openssl_certificate:)
+    super()
+
+    @serial_number = nil
+    @issuer_name = nil
+    @cert_content_without_headers = nil
+    @hash = nil
+    @public_key = nil
+    @public_key_without_headers = nil
+    @public_key_bytes = nil
+    @signature = nil
+
+    @openssl_certificate = openssl_certificate
+
+    parse_certificate
+  end
+
+  private
+
+  attr_reader :openssl_certificate
+
+  def parse_certificate
+    @cert_content_without_headers = openssl_certificate
+      .to_pem
+      .gsub("-----BEGIN CERTIFICATE-----", "")
+      .gsub("-----END CERTIFICATE-----", "")
+      .delete("\n")
+
+    @hash = self.class.generate_base64_hash(cert_content_without_headers)
+
+    # ZATCA expects the issuer name to have spaces after commas, the issue name
+    # looks like "CN=TSZEINVOICE-SubCA-1,DC=extgazt,DC=gov,DC=local"
+    # but ZATCA wants it to be "CN=TSZEINVOICE-SubCA-1, DC=extgazt, DC=gov, DC=local"
+    @issuer_name = openssl_certificate.issuer.to_utf8.gsub(",", ", ")
+
+    @serial_number = openssl_certificate.serial.to_s
+    @cert_content_without_headers = cert_content_without_headers
+    @public_key = openssl_certificate.public_key.to_pem
+    @public_key_without_headers = @public_key
+      .gsub("-----BEGIN PUBLIC KEY-----", "")
+      .gsub("-----END PUBLIC KEY-----", "")
+      .delete("\n")
+
+    @public_key_bytes = parse_public_key_bytes
+
+    parse_signature
+  end
+
+  def parse_public_key_bytes
+    openssl_certificate.public_key.to_der
+  end
+
+  def parse_signature
+    der = openssl_certificate.to_der
+    asn1 = OpenSSL::ASN1.decode(der)
+
+    # The last element of the ASN1 structure is always the signature
+    # The signature would look like so:
+    # "0F\x02!\x00\xEEa\xD3\xEB(<\xE6;P\x19jw3\xBBOO\xB2d\xDB\xEC\xEC\xBDQ\xC6\xB3v\xD4\xE5\x9E\xD8\x13\xAF\x02!\x00\xFA\xD1\xE6\xD0jf#b\xF7^nqc5\xFCx_\x87h\xA7\xB2\xEC\x10\x11B5+\vcB\x05i"
+    @signature = asn1.value[-1].value
+  end
+end