zai_payment 1.1.0 → 1.2.0

data/examples/webhooks.md

@@ -16,6 +16,228 @@ ZaiPayment.configure do |config|
 end
 ```
 
+## Webhook Security: Complete Setup Guide
+
+### Step 1: Generate and Register a Secret Key
+
+Before setting up webhooks, you should establish a secure secret key for signature verification:
+
+```ruby
+require 'securerandom'
+
+# Generate a cryptographically secure secret key (minimum 32 bytes)
+secret_key = SecureRandom.alphanumeric(32)
+# Example output: "aB3xYz9mKpQrTuVwXy2zAbCdEfGhIjKl"
+
+# Store this in your environment variables or secure vault
+# NEVER commit this to version control!
+puts "Add this to your environment variables:"
+puts "ZAI_WEBHOOK_SECRET=#{secret_key}"
+
+# Register the secret key with Zai
+response = ZaiPayment.webhooks.create_secret_key(secret_key: secret_key)
+
+if response.success?
+  puts "✅ Secret key registered successfully with Zai!"
+  puts "Store this key securely - you'll need it to verify webhook signatures"
+else
+  puts "❌ Failed to register secret key"
+end
+```
+
+### Step 2: Create a Webhook
+
+Now create a webhook to receive notifications:
+
+```ruby
+response = ZaiPayment.webhooks.create(
+  url: 'https://your-app.com/webhooks/zai',
+  object_type: 'transactions',
+  enabled: true,
+  description: 'Production webhook for transaction updates'
+)
+
+webhook = response.data
+puts "Created webhook: #{webhook['id']}"
+```
+
+### Step 3: Implement Webhook Endpoint
+
+Here's a complete Rails controller example with signature verification:
+
+```ruby
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  # Skip CSRF token verification for webhook endpoints
+  skip_before_action :verify_authenticity_token
+  
+  # Add basic rate limiting (if using Rack::Attack or similar)
+  # throttle('webhooks/ip', limit: 100, period: 1.minute)
+
+  def zai_webhook
+    # Read the raw request body - IMPORTANT: Don't parse it first!
+    payload = request.body.read
+    signature_header = request.headers['Webhooks-signature']
+    secret_key = ENV['ZAI_WEBHOOK_SECRET']
+
+    # Verify the signature
+    unless verify_webhook_signature(payload, signature_header, secret_key)
+      Rails.logger.warn "Invalid webhook signature received from #{request.remote_ip}"
+      return render json: { error: 'Invalid signature' }, status: :unauthorized
+    end
+
+    # Parse and process the webhook
+    webhook_data = JSON.parse(payload)
+    process_webhook(webhook_data)
+    
+    # Return 200 to acknowledge receipt
+    render json: { status: 'success' }, status: :ok
+  rescue JSON::ParserError => e
+    Rails.logger.error "Invalid JSON in webhook: #{e.message}"
+    render json: { error: 'Invalid JSON' }, status: :bad_request
+  rescue StandardError => e
+    Rails.logger.error "Webhook processing error: #{e.message}"
+    render json: { error: 'Processing error' }, status: :internal_server_error
+  end
+
+  private
+
+  def verify_webhook_signature(payload, signature_header, secret_key)
+    return false if signature_header.blank?
+
+    ZaiPayment.webhooks.verify_signature(
+      payload: payload,
+      signature_header: signature_header,
+      secret_key: secret_key,
+      tolerance: 300 # 5 minutes - adjust based on your needs
+    )
+  rescue ZaiPayment::Errors::ValidationError => e
+    Rails.logger.warn "Webhook signature validation failed: #{e.message}"
+    false
+  end
+
+  def process_webhook(data)
+    # Log the webhook for debugging
+    Rails.logger.info "Processing Zai webhook: #{data['event']}"
+    
+    # Handle different webhook events
+    case data['event']
+    when 'transaction.created'
+      handle_transaction_created(data)
+    when 'transaction.updated'
+      handle_transaction_updated(data)
+    when 'transaction.completed'
+      handle_transaction_completed(data)
+    else
+      Rails.logger.info "Unhandled webhook event: #{data['event']}"
+    end
+  end
+
+  def handle_transaction_created(data)
+    # Your logic here
+    Rails.logger.info "Transaction created: #{data['transaction']['id']}"
+  end
+
+  def handle_transaction_updated(data)
+    # Your logic here
+    Rails.logger.info "Transaction updated: #{data['transaction']['id']}"
+  end
+
+  def handle_transaction_completed(data)
+    # Your logic here
+    Rails.logger.info "Transaction completed: #{data['transaction']['id']}"
+  end
+end
+```
+
+### Step 4: Configure Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Webhook endpoint
+  post '/webhooks/zai', to: 'webhooks#zai_webhook'
+end
+```
+
+### Step 5: Test Your Webhook
+
+Create a test to verify your implementation:
+
+```ruby
+# spec/controllers/webhooks_controller_spec.rb
+require 'rails_helper'
+
+RSpec.describe WebhooksController, type: :controller do
+  let(:secret_key) { SecureRandom.alphanumeric(32) }
+  let(:webhook_payload) do
+    {
+      event: 'transaction.updated',
+      transaction: {
+        id: 'txn_123',
+        state: 'completed',
+        amount: 1000
+      }
+    }.to_json
+  end
+
+  before do
+    ENV['ZAI_WEBHOOK_SECRET'] = secret_key
+  end
+
+  describe 'POST #zai_webhook' do
+    context 'with valid signature' do
+      it 'processes the webhook successfully' do
+        timestamp = Time.now.to_i
+        signature = ZaiPayment::Resources::Webhook.new.generate_signature(
+          webhook_payload, secret_key, timestamp
+        )
+        
+        request.headers['Webhooks-signature'] = "t=#{timestamp},v=#{signature}"
+        post :zai_webhook, body: webhook_payload
+        
+        expect(response).to have_http_status(:ok)
+        expect(JSON.parse(response.body)['status']).to eq('success')
+      end
+    end
+
+    context 'with invalid signature' do
+      it 'rejects the webhook' do
+        timestamp = Time.now.to_i
+        request.headers['Webhooks-signature'] = "t=#{timestamp},v=invalid_signature"
+        post :zai_webhook, body: webhook_payload
+        
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+
+    context 'with missing signature header' do
+      it 'rejects the webhook' do
+        post :zai_webhook, body: webhook_payload
+        
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+
+    context 'with expired timestamp' do
+      it 'rejects old webhooks to prevent replay attacks' do
+        old_timestamp = Time.now.to_i - 600 # 10 minutes ago
+        signature = ZaiPayment::Resources::Webhook.new.generate_signature(
+          webhook_payload, secret_key, old_timestamp
+        )
+        
+        request.headers['Webhooks-signature'] = "t=#{old_timestamp},v=#{signature}"
+        post :zai_webhook, body: webhook_payload
+        
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+  end
+end
+```
+
+## Basic Webhook Operations
+
 ## List Webhooks
 
 ```ruby
@@ -144,3 +366,270 @@ response.headers        # => Response headers
 response.status         # => HTTP status code
 ```
 
+## Additional Webhook Security Examples
+
+### Generate Signature for Testing
+
+You can generate signatures for testing your webhook implementation:
+
+```ruby
+# Useful for integration tests or webhook simulation
+payload = '{"event": "transaction.updated", "id": "txn_123"}'
+secret_key = ENV['ZAI_WEBHOOK_SECRET']
+timestamp = Time.now.to_i
+
+webhook = ZaiPayment::Resources::Webhook.new
+signature = webhook.generate_signature(payload, secret_key, timestamp)
+
+puts "Signature header: t=#{timestamp},v=#{signature}"
+```
+
+### Verify Signature Manually
+
+If you need more control over the verification process:
+
+```ruby
+webhook = ZaiPayment::Resources::Webhook.new
+
+begin
+  is_valid = webhook.verify_signature(
+    payload: request_body,
+    signature_header: request.headers['Webhooks-signature'],
+    secret_key: ENV['ZAI_WEBHOOK_SECRET'],
+    tolerance: 300
+  )
+  
+  if is_valid
+    puts "✅ Webhook signature is valid"
+  else
+    puts "❌ Webhook signature is invalid"
+  end
+rescue ZaiPayment::Errors::ValidationError => e
+  puts "⚠️ Validation error: #{e.message}"
+end
+```
+
+### Sinatra Example
+
+If you're using Sinatra instead of Rails:
+
+```ruby
+require 'sinatra'
+require 'json'
+require 'zai_payment'
+
+# Configure ZaiPayment
+ZaiPayment.configure do |config|
+  config.environment = :prelive
+  config.client_id = ENV['ZAI_CLIENT_ID']
+  config.client_secret = ENV['ZAI_CLIENT_SECRET']
+  config.scope = ENV['ZAI_SCOPE']
+end
+
+post '/webhooks/zai' do
+  # Read raw request body
+  payload = request.body.read
+  signature_header = request.env['HTTP_WEBHOOKS_SIGNATURE']
+  secret_key = ENV['ZAI_WEBHOOK_SECRET']
+  
+  # Verify signature
+  webhook = ZaiPayment::Resources::Webhook.new
+  
+  begin
+    unless webhook.verify_signature(
+      payload: payload,
+      signature_header: signature_header,
+      secret_key: secret_key
+    )
+      halt 401, { error: 'Invalid signature' }.to_json
+    end
+    
+    # Process webhook
+    data = JSON.parse(payload)
+    logger.info "Received webhook: #{data['event']}"
+    
+    # Your processing logic here
+    
+    status 200
+    { status: 'success' }.to_json
+  rescue ZaiPayment::Errors::ValidationError => e
+    logger.error "Webhook validation failed: #{e.message}"
+    halt 401, { error: e.message }.to_json
+  rescue StandardError => e
+    logger.error "Webhook processing error: #{e.message}"
+    halt 500, { error: 'Processing error' }.to_json
+  end
+end
+```
+
+### Rack Middleware Example
+
+Create reusable middleware for webhook verification:
+
+```ruby
+# lib/middleware/zai_webhook_verifier.rb
+module Middleware
+  class ZaiWebhookVerifier
+    def initialize(app, options = {})
+      @app = app
+      @secret_key = options[:secret_key] || ENV['ZAI_WEBHOOK_SECRET']
+      @tolerance = options[:tolerance] || 300
+      @webhook_path = options[:path] || '/webhooks/zai'
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      
+      # Only verify requests to the webhook path
+      if request.path == @webhook_path && request.post?
+        unless verify_request(request)
+          return [401, { 'Content-Type' => 'application/json' }, 
+                  [{ error: 'Invalid webhook signature' }.to_json]]
+        end
+      end
+      
+      @app.call(env)
+    end
+
+    private
+
+    def verify_request(request)
+      body = request.body.read
+      request.body.rewind # Important: rewind for downstream processing
+      
+      signature_header = request.env['HTTP_WEBHOOKS_SIGNATURE']
+      return false unless signature_header
+      
+      webhook = ZaiPayment::Resources::Webhook.new
+      webhook.verify_signature(
+        payload: body,
+        signature_header: signature_header,
+        secret_key: @secret_key,
+        tolerance: @tolerance
+      )
+    rescue ZaiPayment::Errors::ValidationError
+      false
+    end
+  end
+end
+
+# Usage in config.ru or Rails application.rb:
+use Middleware::ZaiWebhookVerifier, 
+    secret_key: ENV['ZAI_WEBHOOK_SECRET'],
+    tolerance: 300,
+    path: '/webhooks/zai'
+```
+
+### Background Job Processing
+
+For production systems, process webhooks asynchronously:
+
+```ruby
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def zai_webhook
+    payload = request.body.read
+    signature_header = request.headers['Webhooks-signature']
+    
+    # Quick verification
+    unless verify_signature(payload, signature_header)
+      return render json: { error: 'Invalid signature' }, status: :unauthorized
+    end
+    
+    # Enqueue for background processing
+    ZaiWebhookJob.perform_later(payload)
+    
+    # Return immediately
+    render json: { status: 'accepted' }, status: :accepted
+  end
+
+  private
+
+  def verify_signature(payload, signature_header)
+    ZaiPayment.webhooks.verify_signature(
+      payload: payload,
+      signature_header: signature_header,
+      secret_key: ENV['ZAI_WEBHOOK_SECRET']
+    )
+  rescue ZaiPayment::Errors::ValidationError
+    false
+  end
+end
+
+# app/jobs/zai_webhook_job.rb
+class ZaiWebhookJob < ApplicationJob
+  queue_as :webhooks
+  
+  # Retry logic for transient failures
+  retry_on StandardError, wait: :exponentially_longer, attempts: 5
+
+  def perform(payload)
+    data = JSON.parse(payload)
+    
+    # Idempotent processing - check if already processed
+    return if WebhookEvent.exists?(external_id: data['id'])
+    
+    # Process the webhook
+    WebhookEvent.create!(
+      external_id: data['id'],
+      event_type: data['event'],
+      payload: data,
+      processed_at: Time.current
+    )
+    
+    # Handle event
+    case data['event']
+    when 'transaction.completed'
+      TransactionProcessor.process_completion(data['transaction'])
+    when 'transaction.failed'
+      TransactionProcessor.process_failure(data['transaction'])
+    end
+  end
+end
+```
+
+### Idempotency Pattern
+
+Ensure webhooks are processed only once:
+
+```ruby
+# app/models/webhook_event.rb
+class WebhookEvent < ApplicationRecord
+  # Columns: external_id, event_type, payload (jsonb), processed_at, created_at
+  
+  validates :external_id, presence: true, uniqueness: true
+  
+  def self.process_if_new(webhook_data)
+    # Use database constraint to ensure atomicity
+    transaction do
+      event = create!(
+        external_id: webhook_data['id'],
+        event_type: webhook_data['event'],
+        payload: webhook_data
+      )
+      
+      yield event if block_given?
+      
+      event.update!(processed_at: Time.current)
+    end
+  rescue ActiveRecord::RecordNotUnique
+    Rails.logger.info "Webhook already processed: #{webhook_data['id']}"
+    false
+  end
+end
+
+# Usage:
+def process_webhook(data)
+  WebhookEvent.process_if_new(data) do |event|
+    # Your processing logic here
+    # This block only runs if the webhook is new
+    case event.event_type
+    when 'transaction.completed'
+      handle_completion(data)
+    end
+  end
+end
+```
+

data/lib/zai_payment/resources/webhook.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'openssl'
+require 'base64'
+
 module ZaiPayment
   module Resources
     # Webhook resource for managing Zai webhooks
@@ -130,6 +133,102 @@ module ZaiPayment
         client.delete("/webhooks/#{webhook_id}")
       end
 
+      # Create a secret key for webhook signature verification
+      #
+      # @param secret_key [String] the secret key to use for HMAC signature generation
+      #   Must be ASCII characters and at least 32 bytes in size
+      # @return [Response] the API response
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   secret_key = SecureRandom.alphanumeric(32)
+      #   response = webhooks.create_secret_key(secret_key: secret_key)
+      #
+      # @see https://developer.hellozai.com/reference/createsecretkey
+      # @see https://developer.hellozai.com/docs/verify-webhook-signatures
+      def create_secret_key(secret_key:)
+        validate_presence!(secret_key, 'secret_key')
+        validate_secret_key!(secret_key)
+
+        body = { secret_key: secret_key }
+        client.post('/webhooks/secret_key', body: body)
+      end
+
+      # Verify webhook signature
+      #
+      # This method verifies that a webhook request came from Zai by validating
+      # the HMAC SHA256 signature in the Webhooks-signature header.
+      #
+      # @param payload [String] the raw request body (JSON string)
+      # @param signature_header [String] the Webhooks-signature header value
+      # @param secret_key [String] your secret key used for signature generation
+      # @param tolerance [Integer] maximum age of webhook in seconds (default: 300 = 5 minutes)
+      # @return [Boolean] true if signature is valid and within tolerance
+      # @raise [Errors::ValidationError] if signature is invalid or timestamp is outside tolerance
+      #
+      # @example
+      #   # In your webhook endpoint (e.g., Rails controller)
+      #   def webhook
+      #     payload = request.body.read
+      #     signature_header = request.headers['Webhooks-signature']
+      #     secret_key = ENV['ZAI_WEBHOOK_SECRET']
+      #
+      #     if ZaiPayment.webhooks.verify_signature(
+      #       payload: payload,
+      #       signature_header: signature_header,
+      #       secret_key: secret_key
+      #     )
+      #       # Process webhook
+      #       render json: { status: 'success' }
+      #     else
+      #       render json: { error: 'Invalid signature' }, status: :unauthorized
+      #     end
+      #   end
+      #
+      # @see https://developer.hellozai.com/docs/verify-webhook-signatures
+      def verify_signature(payload:, signature_header:, secret_key:, tolerance: 300)
+        validate_presence!(payload, 'payload')
+        validate_presence!(signature_header, 'signature_header')
+        validate_presence!(secret_key, 'secret_key')
+
+        # Extract timestamp and signature from header
+        timestamp, signatures = parse_signature_header(signature_header)
+
+        # Verify timestamp is within tolerance (prevent replay attacks)
+        verify_timestamp!(timestamp, tolerance)
+
+        # Generate expected signature
+        expected_signature = generate_signature(payload, secret_key, timestamp)
+
+        # Compare signatures using constant-time comparison
+        signatures.any? { |sig| secure_compare(expected_signature, sig) }
+      end
+
+      # Generate a signature for webhook verification
+      #
+      # This is a utility method that can be used for testing or generating
+      # signatures for webhook simulation.
+      #
+      # @param payload [String] the request body (JSON string)
+      # @param secret_key [String] the secret key
+      # @param timestamp [Integer] the Unix timestamp (defaults to current time)
+      # @return [String] the base64url-encoded HMAC SHA256 signature
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   signature = webhooks.generate_signature(
+      #     '{"event": "status_updated"}',
+      #     'my_secret_key'
+      #   )
+      #
+      # @see https://developer.hellozai.com/docs/verify-webhook-signatures
+      def generate_signature(payload, secret_key, timestamp = Time.now.to_i)
+        signed_payload = "#{timestamp}.#{payload}"
+        digest = OpenSSL::Digest.new('sha256')
+        hash = OpenSSL::HMAC.digest(digest, secret_key, signed_payload)
+        Base64.urlsafe_encode64(hash, padding: false)
+      end
+
       private
 
       def validate_id!(value, field_name)
@@ -152,6 +251,81 @@ module ZaiPayment
       rescue URI::InvalidURIError
         raise Errors::ValidationError, 'url must be a valid URL'
       end
+
+      def validate_secret_key!(secret_key)
+        # Check if it's ASCII
+        raise Errors::ValidationError, 'secret_key must contain only ASCII characters' unless secret_key.ascii_only?
+
+        # Check minimum length (32 bytes)
+        return unless secret_key.bytesize < 32
+
+        raise Errors::ValidationError, 'secret_key must be at least 32 bytes in size'
+      end
+
+      def parse_signature_header(header)
+        # Format: "t=1257894000,v=signature1,v=signature2"
+        parts = header.split(',').map(&:strip)
+
+        timestamp, signatures = extract_timestamp_and_signatures(parts)
+
+        validate_timestamp_presence!(timestamp)
+        validate_signatures_presence!(signatures)
+
+        [timestamp, signatures]
+      end
+
+      def extract_timestamp_and_signatures(parts)
+        timestamp = nil
+        signatures = []
+
+        parts.each do |part|
+          key, value = part.split('=', 2)
+          case key
+          when 't'
+            timestamp = value.to_i
+          when 'v'
+            signatures << value
+          end
+        end
+
+        [timestamp, signatures]
+      end
+
+      def validate_timestamp_presence!(timestamp)
+        return unless timestamp.nil? || timestamp.zero?
+
+        raise Errors::ValidationError, 'Invalid signature header: missing or invalid timestamp'
+      end
+
+      def validate_signatures_presence!(signatures)
+        raise Errors::ValidationError, 'Invalid signature header: missing signature' if signatures.empty?
+      end
+
+      def verify_timestamp!(timestamp, tolerance)
+        current_time = Time.now.to_i
+        time_diff = (current_time - timestamp).abs
+
+        return unless time_diff > tolerance
+
+        raise Errors::ValidationError,
+              "Webhook timestamp is outside tolerance (#{time_diff}s vs #{tolerance}s max). " \
+              'This may be a replay attack.'
+      end
+
+      # Constant-time string comparison to prevent timing attacks
+      # Uses OpenSSL's secure_compare if available, otherwise falls back to manual comparison
+      def secure_compare(str_a, str_b)
+        return false unless str_a.bytesize == str_b.bytesize
+
+        if defined?(OpenSSL.fixed_length_secure_compare)
+          OpenSSL.fixed_length_secure_compare(str_a, str_b)
+        else
+          # Fallback for older Ruby versions
+          result = 0
+          str_a.bytes.zip(str_b.bytes) { |x, y| result |= x ^ y }
+          result.zero?
+        end
+      end
     end
   end
 end

data/lib/zai_payment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZaiPayment
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end