feat: add webhook verification (#46)

* feat: add webhook verification

* update gemfile

* wip

* wip

* wip

* wip

Author: Ashutosh-Bhadauriya

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    authsignal-ruby (5.1.1)
+    authsignal-ruby (5.2.0)
       faraday (>= 2.0.1)
       faraday-retry (~> 2.2)
 

README.md

@@ -2,7 +2,10 @@
 
 # Authsignal Ruby SDK
 
-The Authsignal Ruby library for server-side applications.
+[![Gem Version](https://img.shields.io/gem/v/authsignal-ruby.svg)](https://rubygems.org/gems/authsignal-ruby)
+[![License](https://img.shields.io/github/license/authsignal/authsignal-ruby.svg)](https://github.com/authsignal/authsignal-ruby/blob/main/LICENSE.txt)
+
+The official Authsignal Ruby library for server-side applications. Use this SDK to easily integrate Authsignal's multi-factor authentication (MFA) and passwordless features into your Ruby backend.
 
 ## Installation
 
@@ -12,48 +15,42 @@ Add this line to your application's Gemfile:
 gem "authsignal-ruby"
 ```
 
-## Documentation
-
-Refer to our [SDK documentation](https://docs.authsignal.com/sdks/server/overview) for information on how to use this SDK.
-
-Or check out our [Ruby on Rails Quickstart Guide](https://docs.authsignal.com/integrations/ruby-on-rails).
+And then execute:
+```bash
+bundle install
+```
 
-### Response & Error handling
+Or install it yourself as:
+```bash
+gem install authsignal-ruby
+```
 
-The Authsignal SDK offers two response formats. By default, its methods return the payload in hash format.
+## Getting started
 
-Example:
+Initialize the Authsignal client with your secret key from the [Authsignal Portal](https://portal.authsignal.com/) and the API URL for your region.
 
 ```ruby
-Authsignal.enroll_verified_authenticator(
-  user_id: 'AS_001',
-  attributes: {
-    verification_method: 'INVALID',
-    email: '[email protected]'
-  }
-)
-
-# returns:
-{
-  "error": "invalid_request",
-  "errorCode": "invalid_request",
-  "errorDescription": "body.verificationMethod must be equal to one of the allowed values - allowedValues: AUTHENTICATOR_APP,EMAIL_MAGIC_LINK,EMAIL_OTP,SMS"
-}
+require 'authsignal'
+
+# Initialize the client
+Authsignal.setup do |config|
+  config.api_secret_key = ENV['AUTHSIGNAL_SECRET_KEY']
+  config.api_url = ENV['AUTHSIGNAL_API_URL'] # Use region-specific URL
+end
 ```
 
-All methods have a bang (!) counterpart that raises an Authsignal::ApiError if the request fails.
+### API URLs by region
 
-Example:
+| Region      | API URL                          |
+| ----------- | -------------------------------- |
+| US (Oregon) | https://api.authsignal.com/v1    |
+| AU (Sydney) | https://au.api.authsignal.com/v1 |
+| EU (Dublin) | https://eu.api.authsignal.com/v1 |
 
-```ruby
-Authsignal.enroll_verified_authenticator!(
-  user_id: 'AS_001',
-  attributes: {
-    verification_method: 'INVALID',
-    email: '[email protected]'
-  }
-)
-
-# raise:
-<Authsignal::ApiError: AuthsignalError: 400 - body.verificationMethod must be equal to one of the allowed values - allowedValues: AUTHENTICATOR_APP,EMAIL_MAGIC_LINK,EMAIL_OTP,SMS.
-```
+## License
+
+This SDK is licensed under the [MIT License](LICENSE.txt).
+
+## Documentation
+
+For more information and advanced usage examples, refer to the official [Authsignal server-Side SDK documentation](https://docs.authsignal.com/sdks/server/overview).

lib/authsignal.rb

@@ -4,11 +4,13 @@
 require "authsignal/client"
 require "authsignal/configuration"
 require "authsignal/api_error"
+require "authsignal/invalid_signature_error"
+require "authsignal/webhook"
 require "authsignal/middleware/json_response"
 require "authsignal/middleware/json_request"
 
 module Authsignal
-    NON_API_METHODS = [:setup, :configuration, :default_configuration]
+    NON_API_METHODS = [:setup, :configuration, :default_configuration, :webhook]
 
     class << self
         attr_writer :configuration
@@ -25,6 +27,10 @@ def default_configuration
             configuration.defaults
         end
 
+        def webhook
+            @webhook ||= Webhook.new(configuration.api_secret_key)
+        end
+
         def get_user(user_id:)
             response = Client.new.get_user(user_id: user_id)
 

lib/authsignal/invalid_signature_error.rb

@@ -0,0 +1,7 @@
+module Authsignal
+  class InvalidSignatureError < StandardError
+    def initialize(message)
+      super(message)
+    end
+  end
+end

lib/authsignal/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Authsignal
-  VERSION = "5.1.1"
+  VERSION = "5.2.0"
 end

lib/authsignal/webhook.rb

@@ -0,0 +1,83 @@
+require 'openssl'
+require 'json'
+require 'base64'
+
+module Authsignal
+  DEFAULT_TOLERANCE = 5
+
+  class Webhook
+    VERSION = "v2"
+
+    attr_reader :api_secret_key
+
+    def initialize(api_secret_key)
+      @api_secret_key = api_secret_key
+    end
+
+    def construct_event(payload, signature, tolerance = DEFAULT_TOLERANCE)
+      parsed_signature = parse_signature(signature)
+
+      seconds_since_epoch = Time.now.to_i
+
+      if tolerance > 0 && parsed_signature[:timestamp] < seconds_since_epoch - (tolerance * 60)
+        raise InvalidSignatureError, "Timestamp is outside the tolerance zone."
+      end
+
+      hmac_content = "#{parsed_signature[:timestamp]}.#{payload}"
+
+      computed_signature = OpenSSL::HMAC.digest(
+        OpenSSL::Digest.new('sha256'),
+        @api_secret_key,
+        hmac_content
+      )
+      computed_signature_base64 = Base64.strict_encode64(computed_signature).delete('=')
+
+      match = false
+
+      parsed_signature[:signatures].each do |sig|
+        if sig == computed_signature_base64
+          match = true
+          break
+        end
+      end
+
+      unless match
+        raise InvalidSignatureError, "Signature mismatch."
+      end
+
+      JSON.parse(payload, symbolize_names: true)
+    end
+
+    def parse_signature(value)
+      result = {
+        timestamp: -1,
+        signatures: []
+      }
+
+      return handle_invalid_signature unless value
+
+      value.split(',').each do |item|
+        kv = item.split('=')
+        next unless kv.length == 2
+
+        if kv[0] == 't'
+          result[:timestamp] = kv[1].to_i
+        elsif kv[0] == VERSION
+          result[:signatures] << kv[1]
+        end
+      end
+
+      if result[:timestamp] == -1 || result[:signatures].empty?
+        handle_invalid_signature
+      end
+
+      result
+    end
+
+    private
+
+    def handle_invalid_signature
+      raise InvalidSignatureError, "Signature format is invalid."
+    end
+  end
+end

spec/authsignal/webhook_spec.rb

@@ -0,0 +1,121 @@
+require 'json'
+require 'openssl'
+require 'base64'
+
+RSpec.describe Authsignal::Webhook do
+  let(:api_url) { ENV['AUTHSIGNAL_API_URL'] }
+  let(:api_secret_key) { ENV['AUTHSIGNAL_API_SECRET_KEY'] }
+
+  before do
+    raise "AUTHSIGNAL_API_URL is undefined in env" unless api_url
+    raise "AUTHSIGNAL_API_SECRET_KEY is undefined in env" unless api_secret_key
+
+    Authsignal.setup do |config|
+      config.api_secret_key = api_secret_key
+      config.api_url = api_url
+    end
+  end
+
+  describe "webhook verification" do
+    it "raises error for invalid signature format" do
+      payload = JSON.generate({})
+      signature = "123"
+
+      expect {
+        Authsignal.webhook.construct_event(payload, signature)
+      }.to raise_error(Authsignal::InvalidSignatureError, "Signature format is invalid.")
+    end
+
+    it "raises error for timestamp outside tolerance zone" do
+      payload = JSON.generate({})
+      signature = "t=1630000000,v2=invalid_signature"
+
+      expect {
+        Authsignal.webhook.construct_event(payload, signature)
+      }.to raise_error(Authsignal::InvalidSignatureError, "Timestamp is outside the tolerance zone.")
+    end
+
+    it "raises error for invalid computed signature" do
+      payload = JSON.generate({})
+      timestamp = Time.now.to_i
+      signature = "t=#{timestamp},v2=invalid_signature"
+
+      expect {
+        Authsignal.webhook.construct_event(payload, signature)
+      }.to raise_error(Authsignal::InvalidSignatureError, "Signature mismatch.")
+    end
+
+    it "validates a valid signature" do
+      payload = JSON.generate({
+        version: 1,
+        id: "bc1598bc-e5d6-4c69-9afb-1a6fe3469d6e",
+        source: "https://authsignal.com",
+        time: "2025-02-20T01:51:56.070Z",
+        tenantId: "7752d28e-e627-4b1b-bb81-b45d68d617bc",
+        type: "email.created",
+        data: {
+          to: "[email protected]",
+          code: "157743",
+          userId: "b9f74d36-fcfc-4efc-87f1-3664ab5a7fb0",
+          actionCode: "accountRecovery",
+          idempotencyKey: "ba8c1a7c-775d-4dff-9abe-be798b7b8bb9",
+          verificationMethod: "EMAIL_OTP"
+        }
+      })
+
+      tolerance = -1
+      timestamp = Time.now.to_i
+
+      hmac_content = "#{timestamp}.#{payload}"
+      computed_signature = OpenSSL::HMAC.digest(
+        OpenSSL::Digest.new('sha256'),
+        api_secret_key,
+        hmac_content
+      )
+      signature_b64 = Base64.strict_encode64(computed_signature).delete('=')
+      signature = "t=#{timestamp},v2=#{signature_b64}"
+
+      event = Authsignal.webhook.construct_event(payload, signature, tolerance)
+
+      expect(event).not_to be_nil
+      expect(event[:version]).to eq(1)
+      expect(event[:data][:actionCode]).to eq("accountRecovery")
+    end
+
+    it "validates a signature when 2 API keys are active" do
+      payload = JSON.generate({
+        version: 1,
+        id: "af7be03c-ea8f-4739-b18e-8b48fcbe4e38",
+        source: "https://authsignal.com",
+        time: "2025-02-20T01:47:17.248Z",
+        tenantId: "7752d28e-e627-4b1b-bb81-b45d68d617bc",
+        type: "email.created",
+        data: {
+          to: "[email protected]",
+          code: "718190",
+          userId: "b9f74d36-fcfc-4efc-87f1-3664ab5a7fb0",
+          actionCode: "accountRecovery",
+          idempotencyKey: "68d68190-fac9-4e91-b277-c63d31d3c6b1",
+          verificationMethod: "EMAIL_OTP"
+        }
+      })
+
+      tolerance = -1
+      timestamp = Time.now.to_i
+
+      hmac_content = "#{timestamp}.#{payload}"
+      computed_signature = OpenSSL::HMAC.digest(
+        OpenSSL::Digest.new('sha256'),
+        api_secret_key,
+        hmac_content
+      )
+      signature_b64 = Base64.strict_encode64(computed_signature).delete('=')
+      
+      signature = "t=#{timestamp},v2=#{signature_b64},v2=oldKeySignature123"
+
+      event = Authsignal.webhook.construct_event(payload, signature, tolerance)
+
+      expect(event).not_to be_nil
+    end
+  end
+end