zatca-sdk 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdfd39a00f730f2ea0756c860af60ed558c3ca6b85d232cfa2aeb8dfddd82de3
+  data.tar.gz: 232904047e0134193d9d7af053eb541274088fa2de5e990e3053e3c804a5fbf9
+SHA512:
+  metadata.gz: 40979739078ed6468c27df72ad6814a89b96f40595e9df89862a8d08d11515656afcab048922e55f666a14fc5d8f3202ecd5c42d5d62d64c04ed3cbbab4e848e
+  data.tar.gz: 7774f40179b60921c575d081a9b633ef7fddea630b61a827d89a2bb75c9c8b4a1be997508ab65345aa43afcc924091721774facbb07139c286e9ecb3481b4c46

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+-I lib/zatca

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in zatca.gemspec
+gemspec
+
+gem "rake", "~> 13.0"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Mrsool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# zatca
+![](https://img.shields.io/gem/v/zatca) ![](https://img.shields.io/github/actions/workflow/status/obahareth/zatca/test.yml?branch=main)
+
+A Ruby library for generating QR Codes and e-invoices according to the standard created by ZATCA in Saudi Arabia.
+
+This library supports both Phase 1 and Phase 2. Phase 2 support is still new so there may be bugs. Please [report any issues](https://github.com/obahareth/zatca/issues/new) you find.
+
+# Installation
+
+## Rubygems
+```sh
+gem install zatca
+```
+
+## Bundler
+```sh
+bundle add zatca
+```
+
+# Usage
+
+## Phase 1
+```rb
+require "zatca"
+
+tags = {
+  seller_name: "Mrsool",
+  vat_registration_number: "310228833400003",
+  timestamp: "2021-10-20T19:29:32+03:00",
+  vat_total: "15",
+  invoice_total: "115",
+}
+
+ZATCA.render_qr_code(tags: tags)
+# => data:image/png;base64,...
+# Hint (Try pasting the above into your web browser's address bar)
+```
+
+If you'd like to customize the size of the QR Code you can manually use the generator like so:
+
+```rb
+require "zatca"
+
+tags = ZATCA::Tags.new({
+  seller_name: "Mrsool",
+  vat_registration_number: "310228833400003",
+  timestamp: "2021-10-20T19:29:32+03:00",
+  vat_total: "15",
+  invoice_total: "115",
+})
+
+generator = ZATCA::QRCodeGenerator.new(tags: tags)
+generator.render(size: 512)
+```
+
+## Phase 2
+Documentation lives in the [wiki](https://github.com/obahareth/zatca/wiki)
+
+# Notice of Non-Affiliation and Disclaimer
+This library is not affiliated, associated, authorized, endorsed by, or in any way officially connected with ZATCA (Zakat, Tax and Customs Authority), or any of its subsidiaries or its affiliates. The official ZATCA website can be found at https://zatca.gov.sa.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require_relative "../lib/zatca.rb"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/zatca/client.rb

@@ -0,0 +1,211 @@
+require "httpx"
+require "json"
+
+# This wraps the API described here:
+# https://sandbox.zatca.gov.sa/IntegrationSandbox
+class ZATCA::Client
+  attr_accessor :before_submitting_request, :before_parsing_response
+
+  # 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,
+    verbose: false,
+    before_submitting_request: nil,
+    before_parsing_response: nil
+  )
+    raise "Invalid language: #{language}, Please use one of: #{LANGUAGES}" unless LANGUAGES.include?(language)
+
+    @username = username
+    @password = password
+    @language = language
+    @version = version
+    @verbose = verbose
+
+    @base_url = ENVIRONMENTS_TO_URLS_MAP[environment.to_sym] || PRODUCTION_BASE_URL
+
+    @before_submitting_request = before_submitting_request
+    @before_parsing_response = before_parsing_response
+  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)
+
+    before_submitting_request&.call(method, url, body, headers)
+    log("Requesting #{method} #{url} with\n\nbody: #{body}\n\nheaders: #{headers}\n")
+
+    client = if authenticated
+      authenticated_request_cilent
+    else
+      unauthenticated_request_client
+    end
+
+    response = client.send(method, url, json: body, headers: headers)
+    before_parsing_response&.call(response)
+    log("Raw response: #{response}")
+
+    if response.instance_of?(HTTPX::ErrorResponse)
+      return {
+        message: response.error&.message,
+        details: response.to_s
+      }
+    end
+
+    response_body = response.body.to_s
+
+    parsed_body = if response.headers["Content-Type"] == "application/json"
+      parse_json_or_return_string(response_body)
+    else
+      response_body
+    end
+
+    log("Response body: #{parsed_body}")
+
+    parsed_body
+  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
+
+  def log(message)
+    return unless @verbose
+    message = "\n\n---------------------\n\n#{message}\n\n"
+
+    puts message
+  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

@@ -0,0 +1,28 @@
+require "rqrcode"
+
+module ZATCA
+  class QRCodeGenerator
+    def initialize(tags: nil, base64: nil)
+      @tags = tags
+      @base64 = base64
+    end
+
+    def render(size: 256)
+      qr_code = generate
+
+      qr_code.as_png(size: size, border_modules: 2)&.to_data_url
+    end
+
+    private
+
+    def generate
+      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