zatca 0.1.2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3d50ea1cc7ced6ae04db6b019bbb93b89acd164c93ce6bf0f918e93d3300ca2
-  data.tar.gz: 29217d567f38527e15424d822c681e84c44de620f1212658f49fd7e9c9d28a46
+  metadata.gz: dfcfffb30bc80671008a9f4d85bc6300f7bed524f02919a35314be134f6ced61
+  data.tar.gz: b5fdeac07afe47aabcb05284283a4197ddaf55262961d34dd953a7e9d74f6487
 SHA512:
-  metadata.gz: 3b3c1935011617463f0adee23e3590eddf956be5df53dd6adcd56e1f0c0ba97135faabcb5c97baa93b0565e04dcd2ffde0136573751c12d390f531a5cdccc576
-  data.tar.gz: b1f4612a7c601565791d14d21bae937ef0c7728e3e2aeada65611b7db7a10d12261ebaf2f8b3c56ff6bb5f793173022ea3c26ae126732e3038d17fb27903ca69
+  metadata.gz: 9905e39f50b48661abc536d803254b99dbb7aa4c8a200e3b2c80b9292080aa5d5fa64f419ccf2d5e9c368691ce068cfab96a6373dcc42e9fa9dfc037b3639128
+  data.tar.gz: f3b19d710fce67255bd151bdd1913e900419fddf7343b547a88eb86ebc21b8aaecc40537c1b6a0e58ce0f79b4002667780a3768b95a7042c03b87faca2268038

data/README.md

@@ -1,9 +1,9 @@
 # zatca
 ![](https://img.shields.io/gem/v/zatca) ![](https://img.shields.io/github/workflow/status/mrsool/zatca/Ruby)
 
-A Ruby library for generating QR Codes for the e-invoice standard by ZATCA in Saudi Arabia.
+A Ruby library for generating QR Codes and e-invoices according to the standard created by ZATCA in Saudi Arabia.
 
-✅ Validated to have the same output as [ZATCA's SDK](https://zatca.gov.sa/en/E-Invoicing/SystemsDevelopers/ComplianceEnablementToolbox/Pages/DownloadSDK.aspx) as of 12 November 2021.
+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/mrsool/zatca/issues/new) you find.
 
 # Installation
 
@@ -19,6 +19,7 @@ bundle add zatca
 
 # Usage
 
+## Phase 1
 ```rb
 require "zatca"
 
@@ -51,3 +52,11 @@ tags = ZATCA::Tags.new({
 generator = ZATCA::QRCodeGenerator.new(tags)
 generator.render(size: 512)
 ```
+
+## Phase 2
+Documentation lives in the [wiki](https://github.com/mrsool/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/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

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