google_pay_ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11c693c4ee510867c2a52137125cbb477c076e966ebb8341643ade2138a85418
+  data.tar.gz: aae173c01a2bb5f41255e6c372e947dbfcb4e0461a13234aefe2ab2ca77accba
+SHA512:
+  metadata.gz: a15ac114c7aece47d4e96e89dbe59ed0f52913fac131d8bc2854ac73c992c2323c8ba4c77440b48fb69124f5e4b069cf7b2a17a5c43d7e4fc9462fa8c86bcab7
+  data.tar.gz: 9ecb09181a31652d1bb2fada7f3251bf7d247cb5a09fe32d7fabcebe0f6ef54d8a29931aae810338765f6a6a78c432742eff1d596ee35f04d72c4b4b03e88875

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-02-05
+
+### Added
+- Initial release
+- ECv2 protocol support for Google Pay token decryption
+- Multiple merchant key support for key rotation
+- Pure Ruby implementation using OpenSSL
+- Comprehensive error handling with detailed error messages
+- Support for both string and symbol keys in token hashes
+
+### Features
+- `GooglePaymentMethodTokenContext` class for managing decryption context
+- `EcV2DecryptionStrategy` class implementing ECv2 decryption algorithm
+- `GooglePaymentDecryptionError` exception class with detailed error tracking
+- ECDH shared secret computation
+- HKDF key derivation
+- HMAC verification
+- AES-256-CTR decryption

data/LICENSE.txt

@@ -0,0 +1,9 @@
+
+
+Copyright <2026> <Sahil Gadimbayli>
+
+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,158 @@
+# GooglePayRuby
+
+A Ruby utility for securely decrypting Google Pay PaymentMethodTokens using the ECv2 protocol. This gem is inspired from [Basis Theory google-pay-js](https://github.com/Basis-Theory/google-pay-js) library.
+
+## Features
+
+- **Google Pay PaymentMethodToken Decryption**: Securely decrypt user-authorized Google Pay transaction tokens using easy-to-use interfaces
+- **Key Rotation Support**: Handle multiple private keys simultaneously to support seamless key rotation without missing payments
+- **Pure Ruby Implementation**: No external dependencies beyond OpenSSL (included in Ruby standard library)
+- **ECv2 Protocol Support**: Implements Google Pay's ECv2 encryption protocol
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'google_pay_ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install google_pay_ruby
+```
+
+## Google Pay Setup
+
+Follow [Google Pay API guides](https://developers.google.com/pay/api) for your platform. To use this library, you need to:
+
+1. Be PCI Level 1 certified
+2. Choose tokenization type `DIRECT`
+3. Generate and register your encryption keys with Google
+
+⚠️ **Important**: If you are not PCI Level 1 certified, consider using `PAYMENT_GATEWAY` tokenization type or contact a payment gateway provider.
+
+## Usage
+
+### Basic Example
+
+```ruby
+require 'google_pay_ruby'
+
+# Load your private key (from file, KMS, secrets manager, etc.)
+private_key_pem = File.read('path/to/your/private_key.pem')
+
+# Create the decryption context
+context = GooglePayRuby::GooglePaymentMethodTokenContext.new(
+  merchants: [
+    {
+      identifier: 'my-merchant-identifier',  # Optional, for debugging
+      private_key_pem: private_key_pem
+    }
+  ]
+)
+
+# Get the token from Google Pay API response
+token = {
+  'protocolVersion' => 'ECv2',
+  'signature' => '...',
+  'signedMessage' => '{"encryptedMessage":"...","ephemeralPublicKey":"...","tag":"..."}'
+}
+
+# Decrypt the token
+begin
+  decrypted_data = context.decrypt(token)
+  
+  puts "PAN: #{decrypted_data['paymentMethodDetails']['pan']}"
+  puts "Expiration: #{decrypted_data['paymentMethodDetails']['expirationMonth']}/#{decrypted_data['paymentMethodDetails']['expirationYear']}"
+  puts "Cryptogram: #{decrypted_data['paymentMethodDetails']['cryptogram']}"
+rescue GooglePayRuby::GooglePaymentDecryptionError => e
+  puts "Decryption failed: #{e.message}"
+end
+```
+
+### Key Rotation Support
+
+Handle key rotation gracefully by providing multiple private keys:
+
+```ruby
+context = GooglePayRuby::GooglePaymentMethodTokenContext.new(
+  merchants: [
+    {
+      identifier: 'current-key',
+      private_key_pem: File.read('current_key.pem')
+    },
+    {
+      identifier: 'previous-key',
+      private_key_pem: File.read('previous_key.pem')
+    }
+  ]
+)
+
+# The library will try each key until decryption succeeds
+decrypted_data = context.decrypt(token)
+```
+
+### Decrypted Data Structure
+
+The decrypted payment data contains:
+
+```ruby
+{
+  "gatewayMerchantId" => "your-gateway-merchant-id",
+  "messageExpiration" => "1234567890123",
+  "messageId" => "AH2Ejtc...",
+  "paymentMethod" => "CARD",
+  "paymentMethodDetails" => {
+    "pan" => "4111111111111111",
+    "expirationMonth" => 12,
+    "expirationYear" => 2025,
+    "authMethod" => "CRYPTOGRAM_3DS",
+    "cryptogram" => "AAAAAA...",
+    "eciIndicator" => "05"
+  }
+}
+```
+
+## Error Handling
+
+The gem raises `GooglePayRuby::GooglePaymentDecryptionError` when decryption fails:
+
+```ruby
+begin
+  decrypted_data = context.decrypt(token)
+rescue GooglePayRuby::GooglePaymentDecryptionError => e
+  # Access detailed error information
+  puts e.message
+  puts e.full_message  # Includes details from all attempted keys
+  
+  # Access individual errors
+  e.errors.each do |error|
+    puts "Merchant: #{error.merchant_identifier}"
+    puts "Error: #{error.message}"
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `ruby test/test_decrypt.rb` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/better-payment/google-pay-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+This Ruby implementation is inspired from [Basis Theory google-pay-js](https://github.com/Basis-Theory/google-pay-js) library.

data/lib/google_pay_ruby/ec_v2_decryption_strategy.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'json'
+
+module GooglePayRuby
+  class EcV2DecryptionStrategy
+    def initialize(private_key_pem)
+      @private_key = OpenSSL::PKey::EC.new(private_key_pem)
+    end
+
+    def decrypt(signed_message)
+      parsed_message = JSON.parse(signed_message)
+      
+      ephemeral_public_key = parsed_message['ephemeralPublicKey']
+      encrypted_message = parsed_message['encryptedMessage']
+      tag = parsed_message['tag']
+
+      shared_key = get_shared_key(ephemeral_public_key)
+      derived_key = get_derived_key(ephemeral_public_key, shared_key)
+
+      symmetric_encryption_key = derived_key[0...64]
+      mac_key = derived_key[64..-1]
+
+      verify_message_hmac(mac_key, tag, encrypted_message)
+
+      decrypted_message = decrypt_message(encrypted_message, symmetric_encryption_key)
+
+      JSON.parse(decrypted_message)
+    end
+
+    private
+
+    def get_shared_key(ephemeral_public_key_b64)
+      # Decode the ephemeral public key from base64
+      ephemeral_public_key_bytes = Base64.strict_decode64(ephemeral_public_key_b64)
+      
+      # Create an EC point object for the ephemeral public key
+      group = OpenSSL::PKey::EC::Group.new('prime256v1')
+      point = OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new(ephemeral_public_key_bytes, 2))
+
+      # Compute ECDH shared secret directly from the point (OpenSSL 3.0 compatible)
+      shared_secret = @private_key.dh_compute_key(point)
+      
+      shared_secret.unpack1('H*')
+    end
+
+    def get_derived_key(ephemeral_public_key, shared_key)
+      # Concatenate ephemeral public key and shared key
+      info = Base64.strict_decode64(ephemeral_public_key) + [shared_key].pack('H*')
+      
+      # Use HKDF with SHA-256
+      salt = "\x00" * 32
+      
+      # HKDF implementation
+      prk = OpenSSL::HMAC.digest('SHA256', salt, info)
+      
+      # Expand with info="Google" to get 64 bytes
+      t = ''
+      okm = ''
+      counter = 1
+      
+      while okm.length < 64
+        t = OpenSSL::HMAC.digest('SHA256', prk, t + 'Google' + [counter].pack('C'))
+        okm += t
+        counter += 1
+      end
+      
+      okm[0...64].unpack1('H*')
+    end
+
+    def verify_message_hmac(mac_key, tag, encrypted_message)
+      mac_key_bytes = [mac_key].pack('H*')
+      encrypted_message_bytes = Base64.strict_decode64(encrypted_message)
+      
+      calculated_hmac = OpenSSL::HMAC.digest('SHA256', mac_key_bytes, encrypted_message_bytes)
+      calculated_tag = Base64.strict_encode64(calculated_hmac)
+
+      unless calculated_tag == tag
+        raise GooglePaymentDecryptionError, 'Tag is not a valid MAC for the encrypted message'
+      end
+    end
+
+    def decrypt_message(encrypted_message, symmetric_encryption_key)
+      key = [symmetric_encryption_key].pack('H*')
+      iv = "\x00" * 16
+      
+      encrypted_data = Base64.strict_decode64(encrypted_message)
+      
+      decipher = OpenSSL::Cipher.new('AES-256-CTR')
+      decipher.decrypt
+      decipher.key = key
+      decipher.iv = iv
+      
+      decrypted = decipher.update(encrypted_data) + decipher.final
+      
+      decrypted.force_encoding('UTF-8')
+    end
+  end
+end

data/lib/google_pay_ruby/google_payment_decryption_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GooglePayRuby
+  class GooglePaymentDecryptionError < StandardError
+    attr_reader :errors
+
+    def initialize(message, errors = [])
+      @errors = errors
+      super(message)
+    end
+
+    def full_message
+      message_parts = [message]
+      
+      if errors.any?
+        message_parts << "\nDecryption attempts failed:"
+        errors.each_with_index do |error, index|
+          merchant_id = error.respond_to?(:merchant_identifier) ? error.merchant_identifier : "Unknown"
+          message_parts << "  [#{index + 1}] Merchant: #{merchant_id} - #{error.message}"
+        end
+      end
+      
+      message_parts.join("\n")
+    end
+  end
+end

data/lib/google_pay_ruby/google_payment_method_token_context.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module GooglePayRuby
+  class GooglePaymentMethodTokenContext
+    attr_reader :merchants
+
+    def initialize(options)
+      @merchants = options[:merchants] || []
+      
+      if @merchants.empty?
+        raise GooglePaymentDecryptionError.new(
+          'No merchant configuration provided for decryption context.'
+        )
+      end
+      
+      validate_merchant_configurations!
+    end
+
+    def decrypt(token)
+      protocol_version = token['protocolVersion'] || token[:protocolVersion]
+      unless protocol_version == 'ECv2'
+        raise GooglePaymentDecryptionError.new(
+          "Unsupported decryption for protocol version #{protocol_version}"
+        )
+      end
+
+      errors = []
+      signed_message = token['signedMessage'] || token[:signedMessage]
+
+      @merchants.each do |merchant|
+        begin
+          strategy = EcV2DecryptionStrategy.new(merchant[:private_key_pem])
+          return strategy.decrypt(signed_message)
+        rescue StandardError => e
+          e.define_singleton_method(:merchant_identifier) { merchant[:identifier] }
+          errors << e
+        end
+      end
+
+      raise GooglePaymentDecryptionError.new(
+        'Failed to decrypt payment data using provided merchant configuration(s).',
+        errors
+      )
+    end
+
+    private
+
+    def validate_merchant_configurations!
+      @merchants.each_with_index do |merchant, index|
+        unless merchant.is_a?(Hash)
+          raise ArgumentError, "Merchant configuration at index #{index} must be a Hash"
+        end
+        
+        unless merchant[:private_key_pem]
+          raise ArgumentError, "Merchant configuration at index #{index} must include :private_key_pem"
+        end
+      end
+    end
+  end
+end

data/lib/google_pay_ruby/version.rb

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

data/lib/google_pay_ruby.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "google_pay_ruby/version"
+require_relative "google_pay_ruby/google_payment_method_token_context"
+require_relative "google_pay_ruby/ec_v2_decryption_strategy"
+require_relative "google_pay_ruby/google_payment_decryption_error"
+
+module GooglePayRuby
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: google_pay_ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sahil Gadimbayli
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: A Ruby implementation for securely decrypting Google Pay PaymentMethodTokens
+  using ECv2 protocol. Supports key rotation and multiple merchant configurations.
+email:
+- contact@sahilgadimbayli.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/google_pay_ruby.rb
+- lib/google_pay_ruby/ec_v2_decryption_strategy.rb
+- lib/google_pay_ruby/google_payment_decryption_error.rb
+- lib/google_pay_ruby/google_payment_method_token_context.rb
+- lib/google_pay_ruby/version.rb
+homepage: https://github.com/better-payment/google-pay-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/better-payment/google-pay-ruby
+  source_code_uri: https://github.com/better-payment/google-pay-ruby
+  changelog_uri: https://github.com/better-payment/google-pay-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby utility for decrypting Google Pay Tokens
+test_files: []